The public face of Template Haskell
For other documentation, refer to: http://www.haskell.org/haskellwiki/Template_Haskell
- data Q a
- runQ :: Quasi m => Q a -> m a
- report :: Bool -> String -> Q ()
- recover :: Q a -> Q a -> Q a
- reify :: Name -> Q Info
- location :: Q Loc
- runIO :: IO a -> Q a
- isClassInstance :: Name -> [Type] -> Q Bool
- classInstances :: Name -> [Type] -> Q [Name]
- data Name
- mkName :: String -> Name
- newName :: String -> Q Name
- nameBase :: Name -> String
- nameModule :: Name -> Maybe String
- tupleTypeName :: Int -> Name
- tupleDataName :: Int -> Name
- data Dec
- = FunD Name [Clause]
- | ValD Pat Body [Dec]
- | DataD Cxt Name [TyVarBndr] [Con] [Name]
- | NewtypeD Cxt Name [TyVarBndr] Con [Name]
- | TySynD Name [TyVarBndr] Type
- | ClassD Cxt Name [TyVarBndr] [FunDep] [Dec]
- | InstanceD Cxt Type [Dec]
- | SigD Name Type
- | ForeignD Foreign
- | PragmaD Pragma
- | FamilyD FamFlavour Name [TyVarBndr] (Maybe Kind)
- | DataInstD Cxt Name [Type] [Con] [Name]
- | NewtypeInstD Cxt Name [Type] Con [Name]
- | TySynInstD Name [Type] Type
- data Exp
- = VarE Name
- | ConE Name
- | LitE Lit
- | AppE Exp Exp
- | InfixE (Maybe Exp) Exp (Maybe Exp)
- | LamE [Pat] Exp
- | TupE [Exp]
- | CondE Exp Exp Exp
- | LetE [Dec] Exp
- | CaseE Exp [Match]
- | DoE [Stmt]
- | CompE [Stmt]
- | ArithSeqE Range
- | ListE [Exp]
- | SigE Exp Type
- | RecConE Name [FieldExp]
- | RecUpdE Exp [FieldExp]
- data Con
- = NormalC Name [StrictType]
- | RecC Name [VarStrictType]
- | InfixC StrictType Name StrictType
- | ForallC [TyVarBndr] Cxt Con
- data Type
- data TyVarBndr
- data Kind
- type Cxt = [Pred]
- data Pred
- data Match = Match Pat Body [Dec]
- data Clause = Clause [Pat] Body [Dec]
- data Body
- data Guard
- data Stmt
- data Range
- data Lit
- data Pat
- type FieldExp = (Name, Exp)
- type FieldPat = (Name, Pat)
- data Strict
- data Foreign
- data Callconv
- data Safety
- = Unsafe
- | Safe
- | Threadsafe
- data Pragma
- data InlineSpec = InlineSpec Bool Bool (Maybe (Bool, Int))
- data FunDep = FunDep [Name] [Name]
- data FamFlavour
- data Info
- data ClassInstance = ClassInstance {}
- data Loc = Loc {}
- data Fixity = Fixity Int FixityDirection
- data FixityDirection
- defaultFixity :: Fixity
- maxPrecedence :: Int
- type InfoQ = Q Info
- type ExpQ = Q Exp
- type DecQ = Q Dec
- type DecsQ = Q [Dec]
- type ConQ = Q Con
- type TypeQ = Q Type
- type CxtQ = Q Cxt
- type PredQ = Q Pred
- type MatchQ = Q Match
- type ClauseQ = Q Clause
- type BodyQ = Q Body
- type GuardQ = Q Guard
- type StmtQ = Q Stmt
- type RangeQ = Q Range
- type StrictTypeQ = Q StrictType
- type VarStrictTypeQ = Q VarStrictType
- type PatQ = Q Pat
- type FieldPatQ = Q FieldPat
- type InlineSpecQ = Q InlineSpec
- intPrimL :: Integer -> Lit
- wordPrimL :: Integer -> Lit
- floatPrimL :: Rational -> Lit
- doublePrimL :: Rational -> Lit
- integerL :: Integer -> Lit
- rationalL :: Rational -> Lit
- charL :: Char -> Lit
- stringL :: String -> Lit
- stringPrimL :: String -> Lit
- litP :: Lit -> PatQ
- varP :: Name -> PatQ
- tupP :: [PatQ] -> PatQ
- conP :: Name -> [PatQ] -> PatQ
- infixP :: PatQ -> Name -> PatQ -> PatQ
- tildeP :: PatQ -> PatQ
- bangP :: PatQ -> PatQ
- asP :: Name -> PatQ -> PatQ
- wildP :: PatQ
- recP :: Name -> [FieldPatQ] -> PatQ
- listP :: [PatQ] -> PatQ
- sigP :: PatQ -> TypeQ -> PatQ
- viewP :: ExpQ -> PatQ -> PatQ
- fieldPat :: Name -> PatQ -> FieldPatQ
- normalB :: ExpQ -> BodyQ
- guardedB :: [Q (Guard, Exp)] -> BodyQ
- normalG :: ExpQ -> GuardQ
- normalGE :: ExpQ -> ExpQ -> Q (Guard, Exp)
- patG :: [StmtQ] -> GuardQ
- patGE :: [StmtQ] -> ExpQ -> Q (Guard, Exp)
- match :: PatQ -> BodyQ -> [DecQ] -> MatchQ
- clause :: [PatQ] -> BodyQ -> [DecQ] -> ClauseQ
- dyn :: String -> Q Exp
- global :: Name -> ExpQ
- varE :: Name -> ExpQ
- conE :: Name -> ExpQ
- litE :: Lit -> ExpQ
- appE :: ExpQ -> ExpQ -> ExpQ
- infixE :: Maybe ExpQ -> ExpQ -> Maybe ExpQ -> ExpQ
- infixApp :: ExpQ -> ExpQ -> ExpQ -> ExpQ
- sectionL :: ExpQ -> ExpQ -> ExpQ
- sectionR :: ExpQ -> ExpQ -> ExpQ
- lamE :: [PatQ] -> ExpQ -> ExpQ
- lam1E :: PatQ -> ExpQ -> ExpQ
- tupE :: [ExpQ] -> ExpQ
- condE :: ExpQ -> ExpQ -> ExpQ -> ExpQ
- letE :: [DecQ] -> ExpQ -> ExpQ
- caseE :: ExpQ -> [MatchQ] -> ExpQ
- appsE :: [ExpQ] -> ExpQ
- listE :: [ExpQ] -> ExpQ
- sigE :: ExpQ -> TypeQ -> ExpQ
- recConE :: Name -> [Q (Name, Exp)] -> ExpQ
- recUpdE :: ExpQ -> [Q (Name, Exp)] -> ExpQ
- stringE :: String -> ExpQ
- fieldExp :: Name -> ExpQ -> Q (Name, Exp)
- fromE :: ExpQ -> ExpQ
- fromThenE :: ExpQ -> ExpQ -> ExpQ
- fromToE :: ExpQ -> ExpQ -> ExpQ
- fromThenToE :: ExpQ -> ExpQ -> ExpQ -> ExpQ
- arithSeqE :: RangeQ -> ExpQ
- fromR :: ExpQ -> RangeQ
- fromThenR :: ExpQ -> ExpQ -> RangeQ
- fromToR :: ExpQ -> ExpQ -> RangeQ
- fromThenToR :: ExpQ -> ExpQ -> ExpQ -> RangeQ
- doE :: [StmtQ] -> ExpQ
- compE :: [StmtQ] -> ExpQ
- bindS :: PatQ -> ExpQ -> StmtQ
- letS :: [DecQ] -> StmtQ
- noBindS :: ExpQ -> StmtQ
- parS :: [[StmtQ]] -> StmtQ
- forallT :: [TyVarBndr] -> CxtQ -> TypeQ -> TypeQ
- varT :: Name -> TypeQ
- conT :: Name -> TypeQ
- appT :: TypeQ -> TypeQ -> TypeQ
- arrowT :: TypeQ
- listT :: TypeQ
- tupleT :: Int -> TypeQ
- sigT :: TypeQ -> Kind -> TypeQ
- isStrict :: Q Strict
- notStrict :: Q Strict
- strictType :: Q Strict -> TypeQ -> StrictTypeQ
- varStrictType :: Name -> StrictTypeQ -> VarStrictTypeQ
- cxt :: [PredQ] -> CxtQ
- classP :: Name -> [TypeQ] -> PredQ
- equalP :: TypeQ -> TypeQ -> PredQ
- normalC :: Name -> [StrictTypeQ] -> ConQ
- recC :: Name -> [VarStrictTypeQ] -> ConQ
- infixC :: Q (Strict, Type) -> Name -> Q (Strict, Type) -> ConQ
- valD :: PatQ -> BodyQ -> [DecQ] -> DecQ
- funD :: Name -> [ClauseQ] -> DecQ
- tySynD :: Name -> [TyVarBndr] -> TypeQ -> DecQ
- dataD :: CxtQ -> Name -> [TyVarBndr] -> [ConQ] -> [Name] -> DecQ
- newtypeD :: CxtQ -> Name -> [TyVarBndr] -> ConQ -> [Name] -> DecQ
- classD :: CxtQ -> Name -> [TyVarBndr] -> [FunDep] -> [DecQ] -> DecQ
- instanceD :: CxtQ -> TypeQ -> [DecQ] -> DecQ
- sigD :: Name -> TypeQ -> DecQ
- familyNoKindD :: FamFlavour -> Name -> [TyVarBndr] -> DecQ
- familyKindD :: FamFlavour -> Name -> [TyVarBndr] -> Kind -> DecQ
- dataInstD :: CxtQ -> Name -> [TypeQ] -> [ConQ] -> [Name] -> DecQ
- newtypeInstD :: CxtQ -> Name -> [TypeQ] -> ConQ -> [Name] -> DecQ
- tySynInstD :: Name -> [TypeQ] -> TypeQ -> DecQ
- typeFam :: FamFlavour
- dataFam :: FamFlavour
- cCall :: Callconv
- stdCall :: Callconv
- unsafe :: Safety
- safe :: Safety
- threadsafe :: Safety
- forImpD :: Callconv -> Safety -> String -> Name -> TypeQ -> DecQ
- inlineSpecNoPhase :: Bool -> Bool -> InlineSpecQ
- inlineSpecPhase :: Bool -> Bool -> Bool -> Int -> InlineSpecQ
- pragInlD :: Name -> InlineSpecQ -> DecQ
- pragSpecD :: Name -> TypeQ -> DecQ
- class Ppr a where
- pprint :: Ppr a => a -> String
- pprExp :: Precedence -> Exp -> Doc
- pprLit :: Precedence -> Lit -> Doc
- pprPat :: Precedence -> Pat -> Doc
- pprParendType :: Type -> Doc
The monad and its operations
The runIO
function lets you run an I/O computation in the Q
monad.
Take care: you are guaranteed the ordering of calls to runIO
within
a single Q
computation, but not about the order in which splices are run.
Note: for various murky reasons, stdout and stderr handles are not necesarily flushed when the compiler finishes running, so you should flush them yourself.
classInstances :: Name -> [Type] -> Q [Name]Source
classInstances
looks up instaces of a class
Names
For global names (NameG
) we need a totally unique name,
so we must include the name-space of the thing
For unique-numbered things (NameU
), we've got a unique reference
anyway, so no need for name space
For dynamically bound thing (NameS
) we probably want them to
in a context-dependent way, so again we don't want the name
space. For example:
let v = mkName "T" in [| data $v = $v |]
Here we use the same Name for both type constructor and data constructor
NameL and NameG are bound *outside* the TH syntax tree either globally (NameG) or locally (NameL). Ex:
f x = $(h [| (map, x) |])
The map
will be a NameG, and x
wil be a NameL
These Names should never appear in a binding position in a TH syntax tree
mkName :: String -> NameSource
The string can have a .
, thus Foo.baz,
giving a dynamically-bound qualified name,
in which case we want to generate a NameQ
Parse the string to see if it has a . in it so we know whether to generate a qualified or unqualified name It's a bit tricky because we need to parse
Foo.Baz.x as Qual Foo.Baz x
So we parse it from back to front
nameModule :: Name -> Maybe StringSource
The algebraic data types
The lowercase versions (syntax operators) of these constructors are
preferred to these constructors, since they compose better with
quotations ([| |]
) and splices ($( ... )
)
FunD Name [Clause] | { f p1 p2 = b where decs } |
ValD Pat Body [Dec] | { p = b where decs } |
DataD Cxt Name [TyVarBndr] [Con] [Name] | { data Cxt x => T x = A x | B (T x) deriving (Z,W)} |
NewtypeD Cxt Name [TyVarBndr] Con [Name] | { newtype Cxt x => T x = A (B x) deriving (Z,W)} |
TySynD Name [TyVarBndr] Type | { type T x = (x,x) } |
ClassD Cxt Name [TyVarBndr] [FunDep] [Dec] | { class Eq a => Ord a where ds } |
InstanceD Cxt Type [Dec] | { instance Show w => Show [w] where ds } |
SigD Name Type | { length :: [a] -> Int } |
ForeignD Foreign | |
PragmaD Pragma | { {--} } |
FamilyD FamFlavour Name [TyVarBndr] (Maybe Kind) | { type family T a b c :: * } |
DataInstD Cxt Name [Type] [Con] [Name] | { data instance Cxt x => T [x] = A x | B (T x) deriving (Z,W)} |
NewtypeInstD Cxt Name [Type] Con [Name] | { newtype instance Cxt x => T [x] = A (B x) deriving (Z,W)} |
TySynInstD Name [Type] Type | { type instance T (Maybe x) = (x,x) } |
The CompE
constructor represents a list comprehension, and
takes a [Stmt
]. The result expression of the comprehension is
the *last* of these, and should be a NoBindS
.
E.g. translation:
[ f x | x <- xs ]
CompE [BindS (VarP x) (VarE xs), NoBindS (AppE (VarE f) (VarE x))]
VarE Name | { x } |
ConE Name | data T1 = C1 t1 t2; p = {C1} e1 e2 |
LitE Lit | { 5 or |
AppE Exp Exp | { f x } |
InfixE (Maybe Exp) Exp (Maybe Exp) | {x + y} or {(x+)} or {(+ x)} or {(+)} It's a bit gruesome to use an Exp as the operator, but how else can we distinguish constructors from non-constructors? Maybe there should be a var-or-con type? Or maybe we should leave it to the String itself? |
LamE [Pat] Exp | { p1 p2 -> e } |
TupE [Exp] | { (e1,e2) } |
CondE Exp Exp Exp | { if e1 then e2 else e3 } |
LetE [Dec] Exp | { let x=e1; y=e2 in e3 } |
CaseE Exp [Match] | { case e of m1; m2 } |
DoE [Stmt] | { do { p <- e1; e2 } } |
CompE [Stmt] | { [ (x,y) | x <- xs, y <- ys ] } |
ArithSeqE Range | { [ 1 ,2 .. 10 ] } |
ListE [Exp] | { [1,2,3] } |
SigE Exp Type | { e :: t } |
RecConE Name [FieldExp] | { T { x = y, z = w } } |
RecUpdE Exp [FieldExp] | { (f x) { z = w } } |
NormalC Name [StrictType] | C Int a |
RecC Name [VarStrictType] | C { v :: Int, w :: a } |
InfixC StrictType Name StrictType | Int :+ a |
ForallC [TyVarBndr] Cxt Con | forall a. Eq a => C [a] |
CharL Char | |
StringL String | |
IntegerL Integer | Used for overloaded and non-overloaded literals. We don't have a good way to represent non-overloaded literals at the moment. Maybe that doesn't matter? |
RationalL Rational | |
IntPrimL Integer | |
WordPrimL Integer | |
FloatPrimL Rational | |
DoublePrimL Rational | |
StringPrimL String | A primitive C-style string, type Addr# |
Pattern in Haskell given in {}
LitP Lit | { 5 or |
VarP Name | { x } |
TupP [Pat] | { (p1,p2) } |
ConP Name [Pat] | data T1 = C1 t1 t2; {C1 p1 p1} = e |
InfixP Pat Name Pat | foo ({x :+ y}) = e |
TildeP Pat | { ~p } |
BangP Pat | { !p } |
AsP Name Pat | { x @ p } |
WildP | { _ } |
RecP Name [FieldPat] | f (Pt { pointx = x }) = g x |
ListP [Pat] | { [1,2,3] } |
SigP Pat Type | { p :: t } |
ViewP Exp Pat | { e -> p } |
data InlineSpec Source
data FamFlavour Source
data ClassInstance Source
ClassInstance
desribes a single instance of a class
Loc | |
|
data FixityDirection Source
Library functions
Abbreviations
type StrictTypeQ = Q StrictTypeSource
type VarStrictTypeQ = Q VarStrictTypeSource
type InlineSpecQ = Q InlineSpecSource
Constructors lifted to Q
Literals
floatPrimL :: Rational -> LitSource
doublePrimL :: Rational -> LitSource
stringPrimL :: String -> LitSource
Patterns
Pattern Guards
Expressions
Ranges
Ranges with more indirection
Statements
Types
Strictness
strictType :: Q Strict -> TypeQ -> StrictTypeQSource
varStrictType :: Name -> StrictTypeQ -> VarStrictTypeQSource
Class Contexts
normalC :: Name -> [StrictTypeQ] -> ConQSource
recC :: Name -> [VarStrictTypeQ] -> ConQSource
Top Level Declarations
Data
Class
Type Family / Data Family
familyNoKindD :: FamFlavour -> Name -> [TyVarBndr] -> DecQSource
familyKindD :: FamFlavour -> Name -> [TyVarBndr] -> Kind -> DecQSource
Foreign Function Interface (FFI)
Pragmas
Just inline supported so far
inlineSpecNoPhase :: Bool -> Bool -> InlineSpecQSource
inlineSpecPhase :: Bool -> Bool -> Bool -> Int -> InlineSpecQSource
pragInlD :: Name -> InlineSpecQ -> DecQSource
Pretty-printer
pprExp :: Precedence -> Exp -> DocSource
pprLit :: Precedence -> Lit -> DocSource
pprPat :: Precedence -> Pat -> DocSource
pprParendType :: Type -> DocSource