template-haskell-2.5.0.0

Portability | portable
Stability | experimental
Maintainer | libraries@haskell.org

Language.Haskell.TH.Syntax

Contents

- Names
- The algebraic data types
- Internal functions

Description

Abstract syntax definitions for Template Haskell.

Synopsis

- class (Monad m, Functor m) => Quasi m where
  - qNewName :: String -> m Name
  - qReport :: Bool -> String -> m ()
  - qRecover :: m a -> m a -> m a
  - qReify :: Name -> m Info
  - qClassInstances :: Name -> [Type] -> m [Name]
  - qLocation :: m Loc
  - qRunIO :: IO a -> m a
- class Lift t where
  - lift :: t -> Q Exp
- liftString :: String -> Q Exp
- 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 = Name OccName NameFlavour
- mkName :: String -> Name
- newName :: String -> Q Name
- nameBase :: Name -> String
- nameModule :: Name -> Maybe String
- showName :: Name -> String
- showName' :: NameIs -> Name -> String
- data NameIs
  - = Alone
  - | Applied
  - | Infix
- 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
  - = ForallT [TyVarBndr] Cxt Type
  - | VarT Name
  - | ConT Name
  - | TupleT Int
  - | ArrowT
  - | ListT
  - | AppT Type Type
  - | SigT Type Kind
- data TyVarBndr
  - = PlainTV Name
  - | KindedTV Name Kind
- data Kind
  - = StarK
  - | ArrowK Kind Kind
- type Cxt = [Pred]
- data Pred
  - = ClassP Name [Type]
  - | EqualP Type Type
- data Match = Match Pat Body [Dec]
- data Clause = Clause [Pat] Body [Dec]
- data Body
  - = GuardedB [(Guard, Exp)]
  - | NormalB Exp
- data Guard
  - = NormalG Exp
  - | PatG [Stmt]
- data Stmt
  - = BindS Pat Exp
  - | LetS [Dec]
  - | NoBindS Exp
  - | ParS [[Stmt]]
- data Range
  - = FromR Exp
  - | FromThenR Exp Exp
  - | FromToR Exp Exp
  - | FromThenToR Exp Exp Exp
- data Lit
  - = CharL Char
  - | StringL String
  - | IntegerL Integer
  - | RationalL Rational
  - | IntPrimL Integer
  - | WordPrimL Integer
  - | FloatPrimL Rational
  - | DoublePrimL Rational
  - | StringPrimL String
- data Pat
  - = LitP Lit
  - | VarP Name
  - | TupP [Pat]
  - | ConP Name [Pat]
  - | InfixP Pat Name Pat
  - | TildeP Pat
  - | BangP Pat
  - | AsP Name Pat
  - | WildP
  - | RecP Name [FieldPat]
  - | ListP [Pat]
  - | SigP Pat Type
  - | ViewP Exp Pat
- type FieldExp = (Name, Exp)
- type FieldPat = (Name, Pat)
- data ClassInstance = ClassInstance {
  - ci_dfun :: Name
  - ci_tvs :: [TyVarBndr]
  - ci_cxt :: Cxt
  - ci_cls :: Name
  - ci_tys :: [Type]
  }
- data Strict
  - = IsStrict
  - | NotStrict
- data Foreign
  - = ImportF Callconv Safety String Name Type
  - | ExportF Callconv String Name Type
- data Callconv
  - = CCall
  - | StdCall
- data Safety
  - = Unsafe
  - | Safe
  - | Threadsafe
- data Pragma
  - = InlineP Name InlineSpec
  - | SpecialiseP Name Type (Maybe InlineSpec)
- data InlineSpec = InlineSpec Bool Bool (Maybe (Bool, Int))
- type StrictType = (Strict, Type)
- type VarStrictType = (Name, Strict, Type)
- data FunDep = FunDep [Name] [Name]
- data FamFlavour
  - = TypeFam
  - | DataFam
- data Info
  - = ClassI Dec [ClassInstance]
  - | ClassOpI Name Type Name Fixity
  - | TyConI Dec
  - | PrimTyConI Name Int Bool
  - | DataConI Name Type Name Fixity
  - | VarI Name Type (Maybe Dec) Fixity
  - | TyVarI Name Type
- data Loc = Loc {
  - loc_filename :: String
  - loc_package :: String
  - loc_module :: String
  - loc_start :: CharPos
  - loc_end :: CharPos
  }
- type CharPos = (Int, Int)
- data Fixity = Fixity Int FixityDirection
- data FixityDirection
  - = InfixL
  - | InfixR
  - | InfixN
- defaultFixity :: Fixity
- maxPrecedence :: Int
- returnQ :: a -> Q a
- bindQ :: Q a -> (a -> Q b) -> Q b
- sequenceQ :: [Q a] -> Q [a]
- data NameFlavour
  - = NameS
  - | NameQ ModName
  - | NameU Int#
  - | NameL Int#
  - | NameG NameSpace PkgName ModName
- data NameSpace
  - = VarName
  - | DataName
  - | TcClsName
- mkNameG_v :: String -> String -> String -> Name
- mkNameG_d :: String -> String -> String -> Name
- mkNameG_tc :: String -> String -> String -> Name
- type Uniq = Int
- mkNameL :: String -> Uniq -> Name
- mkNameU :: String -> Uniq -> Name
- tupleTypeName :: Int -> Name
- tupleDataName :: Int -> Name
- data OccName
- mkOccName :: String -> OccName
- occString :: OccName -> String
- data ModName
- mkModName :: String -> ModName
- modString :: ModName -> String
- data PkgName
- mkPkgName :: String -> PkgName
- pkgString :: PkgName -> String

# Documentation

class (Monad m, Functor m) => Quasi m where

Methods

qNewName

Arguments

:: String |
-> m Name | Fresh names

qReport

Arguments

:: Bool |
-> String |
-> m () | Report an error (True) or warning (False) ...but carry on; use `fail` to stop

qRecover

Arguments

:: m a | the error handler
-> m a | action which may fail
-> m a | Recover from the monadic `fail`

qReify :: Name -> m Info

qClassInstances :: Name -> [Type] -> m [Name]

qLocation :: m Loc

qRunIO :: IO a -> m a

Input/output (dangerous)

Instances

Quasi IO |
Quasi Q |

class Lift t where

Methods

lift :: t -> Q Exp

Instances

Lift Bool |
Lift Char |
Lift Int |
Lift Integer |
Lift a => Lift [a] |
Lift a => Lift (Maybe a) |
(Lift a, Lift b) => Lift (Either a b) |
(Lift a, Lift b) => Lift (a, b) |
(Lift a, Lift b, Lift c) => Lift (a, b, c) |
(Lift a, Lift b, Lift c, Lift d) => Lift (a, b, c, d) |
(Lift a, Lift b, Lift c, Lift d, Lift e) => Lift (a, b, c, d, e) |
(Lift a, Lift b, Lift c, Lift d, Lift e, Lift f) => Lift (a, b, c, d, e, f) |
(Lift a, Lift b, Lift c, Lift d, Lift e, Lift f, Lift g) => Lift (a, b, c, d, e, f, g) |

liftString :: String -> Q Exp

data Q a

Instances

Monad Q |
Functor Q |
Quasi Q |

runQ :: Quasi m => Q a -> m a

report :: Bool -> String -> Q ()

recover

Arguments

:: Q a | recover with this one
-> Q a | failing action
-> Q a |

reify :: Name -> Q Info

`reify` looks up information about the `Name`

location :: Q Loc

`location` gives you the `Location` at which this computation is spliced.

runIO :: IO a -> Q a

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.

isClassInstance :: Name -> [Type] -> Q Bool

classInstances :: Name -> [Type] -> Q [Name]

`classInstances` looks up instaces of a class

# Names

data Name

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

Constructors

Name OccName NameFlavour |

Instances

Eq Name |
Data Name |
Ord Name |
Show Name |
Typeable Name |
Ppr Name |

mkName :: String -> Name

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

newName :: String -> Q Name

nameBase :: Name -> String

Base, unqualified name.

nameModule :: Name -> Maybe String

showName :: Name -> String

showName' :: NameIs -> Name -> String

data NameIs

Constructors

Alone |
Applied |
Infix |

# The algebraic data types

data Dec

Constructors

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) }

Instances

Eq Dec |
Data Dec |
Show Dec |
Typeable Dec |
Ppr Dec |

data Exp

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))]

Constructors

VarE Name

    { x }

ConE Name

    data T1 = C1 t1 t2; p = {C1} e1 e2

LitE Lit

    { 5 or c}

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 } }

Instances

Eq Exp |
Data Exp |
Show Exp |
Typeable Exp |
Ppr Exp |

data Con

Constructors

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]

Instances

Eq Con |
Data Con |
Show Con |
Typeable Con |
Ppr Con |

data Type

Constructors

ForallT [TyVarBndr] Cxt Type

    forall vars. ctxt -> type

VarT Name

    a

ConT Name

    T

TupleT Int

    (,), (,,), etc.

ArrowT

    ->

ListT

    []

AppT Type Type

    T a b

SigT Type Kind

    t :: k

Instances

Eq Type |
Data Type |
Show Type |
Typeable Type |
Ppr Type |

data TyVarBndr

Constructors

PlainTV Name

    a

KindedTV Name Kind

    (a :: k)

Instances

Eq TyVarBndr |
Data TyVarBndr |
Show TyVarBndr |
Typeable TyVarBndr |
Ppr TyVarBndr |

data Kind

Constructors

StarK

    *

ArrowK Kind Kind

    k1 -> k2

Instances

Eq Kind |
Data Kind |
Show Kind |
Typeable Kind |
Ppr Kind |

type Cxt

Arguments

= [Pred]

    (Eq a, Ord b)

data Pred

Constructors

ClassP Name [Type]

    Eq (Int, a)

EqualP Type Type

    F a ~ Bool

Instances

Eq Pred |
Data Pred |
Show Pred |
Typeable Pred |
Ppr Pred |

data Match

Constructors

Match Pat Body [Dec]

    case e of { pat -> body where decs }

Instances

Eq Match |
Data Match |
Show Match |
Typeable Match |
Ppr Match |

data Clause

Constructors

Clause [Pat] Body [Dec]

    f { p1 p2 = body where decs }

Instances

Eq Clause |
Data Clause |
Show Clause |
Typeable Clause |
Ppr Clause |

data Body

Constructors

GuardedB [(Guard, Exp)]

    f p { | e1 = e2 | e3 = e4 } where ds

NormalB Exp

    f p { = e } where ds

Instances

Eq Body |
Data Body |
Show Body |
Typeable Body |

data Guard

Constructors

NormalG Exp |
PatG [Stmt] |

Instances

Eq Guard |
Data Guard |
Show Guard |
Typeable Guard |

data Stmt

Constructors

BindS Pat Exp |
LetS [Dec] |
NoBindS Exp |
ParS [[Stmt]] |

Instances

Eq Stmt |
Data Stmt |
Show Stmt |
Typeable Stmt |
Ppr Stmt |

data Range

Constructors

FromR Exp |
FromThenR Exp Exp |
FromToR Exp Exp |
FromThenToR Exp Exp Exp |

Instances

Eq Range |
Data Range |
Show Range |
Typeable Range |
Ppr Range |

data Lit

Constructors

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#

Instances

Eq Lit |
Data Lit |
Show Lit |
Typeable Lit |

data Pat

Pattern in Haskell given in `{}`

Constructors

LitP Lit

    { 5 or c }

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 }

Instances

Eq Pat |
Data Pat |
Show Pat |
Typeable Pat |
Ppr Pat |

type FieldExp = (Name, Exp)

type FieldPat = (Name, Pat)

data ClassInstance

`ClassInstance` desribes a single instance of a class

Constructors

ClassInstance |

Fields

ci_dfun :: Name
ci_tvs :: [TyVarBndr]
ci_cxt :: Cxt
ci_cls :: Name
ci_tys :: [Type]

Instances

Data ClassInstance |
Show ClassInstance |
Typeable ClassInstance |
Ppr ClassInstance |

data Strict

Constructors

IsStrict |
NotStrict |

Instances

Eq Strict |
Data Strict |
Show Strict |
Typeable Strict |

data Foreign

Constructors

ImportF Callconv Safety String Name Type |
ExportF Callconv String Name Type |

Instances

Eq Foreign |
Data Foreign |
Show Foreign |
Typeable Foreign |
Ppr Foreign |

data Callconv

Constructors

CCall |
StdCall |

Instances

Eq Callconv |
Data Callconv |
Show Callconv |
Typeable Callconv |

data Safety

Constructors

Unsafe |
Safe |
Threadsafe |

Instances

Eq Safety |
Data Safety |
Show Safety |
Typeable Safety |

data Pragma

Constructors

InlineP Name InlineSpec |
SpecialiseP Name Type (Maybe InlineSpec) |

Instances

Eq Pragma |
Data Pragma |
Show Pragma |
Typeable Pragma |
Ppr Pragma |

data InlineSpec

Constructors

InlineSpec Bool Bool (Maybe (Bool, Int)) |

Instances

Eq InlineSpec |
Data InlineSpec |
Show InlineSpec |
Typeable InlineSpec |

type StrictType = (Strict, Type)

type VarStrictType = (Name, Strict, Type)

data FunDep

Constructors

FunDep [Name] [Name] |

Instances

Eq FunDep |
Data FunDep |
Show FunDep |
Typeable FunDep |
Ppr FunDep |

data FamFlavour

Constructors

TypeFam |
DataFam |

Instances

Eq FamFlavour |
Data FamFlavour |
Show FamFlavour |
Typeable FamFlavour |
Ppr FamFlavour |

data Info

Obtained from `reify` in the `Q` Monad.

Constructors

ClassI Dec [ClassInstance] | A class is reified to its declaration and a list of its instances
ClassOpI Name Type Name Fixity |
TyConI Dec |
PrimTyConI Name Int Bool |
DataConI Name Type Name Fixity |
VarI Name Type (Maybe Dec) Fixity |
TyVarI Name Type |

Instances

Data Info |
Show Info |
Typeable Info |
Ppr Info |

data Loc

Constructors

Loc |

Fields

loc_filename :: String
loc_package :: String
loc_module :: String
loc_start :: CharPos
loc_end :: CharPos

type CharPos = (Int, Int)

data Fixity

Constructors

Fixity Int FixityDirection |

Instances

Eq Fixity |
Data Fixity |
Show Fixity |
Typeable Fixity |

data FixityDirection

Constructors

InfixL |
InfixR |
InfixN |

Instances

Eq FixityDirection |
Data FixityDirection |
Show FixityDirection |
Typeable FixityDirection |

defaultFixity :: Fixity

maxPrecedence :: Int

# Internal functions

returnQ :: a -> Q a

bindQ :: Q a -> (a -> Q b) -> Q b

sequenceQ :: [Q a] -> Q [a]

data NameFlavour

Constructors

NameS | An unqualified name; dynamically bound
NameQ ModName | A qualified name; dynamically bound
NameU Int# | A unique local name
NameL Int# | Local name bound outside of the TH AST
NameG NameSpace PkgName ModName | Global name bound outside of the TH AST: An original name (occurrences only, not binders) Need the namespace too to be sure which thing we are naming

Instances

Eq NameFlavour |

Data NameFlavour

Although the NameFlavour type is abstract, the Data instance is not. The reason for this is that currently we use Data to serialize values in annotations, and in order for that to work for Template Haskell names introduced via the 'x syntax we need gunfold on NameFlavour to work. Bleh!

The long term solution to this is to use the binary package for annotation serialization and then remove this instance. However, to do _that_ we need to wait on binary to become stable, since boot libraries cannot be upgraded seperately from GHC itself.

This instance cannot be derived automatically due to bug #2701

Ord NameFlavour |
Typeable NameFlavour |

data NameSpace

Constructors

VarName | Variables
DataName | Data constructors
TcClsName | Type constructors and classes; Haskell has them in the same name space for now.

Instances

Eq NameSpace |
Data NameSpace |
Ord NameSpace |
Typeable NameSpace |

mkNameG_v :: String -> String -> String -> Name

mkNameG_d :: String -> String -> String -> Name

mkNameG_tc :: String -> String -> String -> Name

type Uniq = Int

mkNameL :: String -> Uniq -> Name

Only used internally

mkNameU :: String -> Uniq -> Name

Only used internally

tupleTypeName

Arguments

:: Int |
-> Name | Type constructor

tupleDataName

Arguments

:: Int |
-> Name | Data constructor

data OccName

Instances

Eq OccName |
Data OccName |
Ord OccName |
Typeable OccName |

mkOccName :: String -> OccName

occString :: OccName -> String

data ModName

Instances

Eq ModName |
Data ModName |
Ord ModName |
Typeable ModName |

mkModName :: String -> ModName

modString :: ModName -> String

data PkgName

Instances

Eq PkgName |
Data PkgName |
Ord PkgName |
Typeable PkgName |

mkPkgName :: String -> PkgName

pkgString :: PkgName -> String