Commit 49f2a3b9 authored by aavogt's avatar aavogt
Browse files

Format most comments for haddock.

parent 7c93bf74
-- The public face of Template Haskell
{- | The public face of Template Haskell
For other documentation, refer to:
<http://www.haskell.org/haskellwiki/Template_Haskell>
-}
module Language.Haskell.TH(
-- The monad and its operations
-- * The monad and its operations
Q, runQ,
report, -- :: Bool -> String -> Q ()
recover, -- :: Q a -> Q a -> Q a
......@@ -9,7 +13,7 @@ module Language.Haskell.TH(
location, -- :: Q Location
runIO, -- :: IO a -> Q a
-- Names
-- * Names
Name,
mkName, -- :: String -> Name
newName, -- :: String -> Q Name
......@@ -17,7 +21,10 @@ module Language.Haskell.TH(
nameModule, -- :: Name -> Maybe String
tupleTypeName, tupleDataName, -- Int -> Name
-- The algebraic data types
-- * 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 (@$( ... )@)
Dec(..), Exp(..), Con(..), Type(..), TyVarBndr(..), Kind(..), Cxt,
Pred(..), Match(..), Clause(..), Body(..), Guard(..), Stmt(..),
Range(..), Lit(..), Pat(..), FieldExp, FieldPat,
......@@ -25,32 +32,62 @@ module Language.Haskell.TH(
InlineSpec(..), FunDep(..), FamFlavour(..), Info(..), Loc(..),
Fixity(..), FixityDirection(..), defaultFixity, maxPrecedence,
-- Library functions
-- * Library functions
-- ** Abbreviations
InfoQ, ExpQ, DecQ, ConQ, TypeQ, CxtQ, PredQ, MatchQ, ClauseQ, BodyQ,
GuardQ, StmtQ, RangeQ, StrictTypeQ, VarStrictTypeQ, PatQ, FieldPatQ,
InlineSpecQ,
-- ** Constructors lifted to 'Q'
-- *** Litterals
intPrimL, wordPrimL, floatPrimL, doublePrimL, integerL, rationalL,
charL, stringL,
-- *** Patterns
litP, varP, tupP, conP, infixP, tildeP, bangP, asP, wildP, recP,
listP, sigP,
fieldPat,
bindS, letS, noBindS, parS,
fromR, fromThenR, fromToR, fromThenToR,
-- *** Pattern Guards
normalB, guardedB, normalG, normalGE, patG, patGE, match, clause,
-- *** Expressions
dyn, global, varE, conE, litE, appE, infixE, infixApp, sectionL, sectionR,
lamE, lam1E, tupE, condE, letE, caseE, doE, compE, arithSeqE, appsE,
fromE, fromThenE, fromToE, fromThenToE,
lamE, lam1E, tupE, condE, letE, caseE, appsE,
listE, sigE, recConE, recUpdE, stringE, fieldExp,
valD, funD, tySynD, dataD, newtypeD, classD, instanceD, sigD, forImpD,
pragInlD, pragSpecD, familyNoKindD, familyKindD, dataInstD,
newtypeInstD, tySynInstD,
cxt, classP, equalP, normalC, recC, infixC,
-- **** Ranges
fromE, fromThenE, fromToE, fromThenToE,
-- ***** Ranges with more indirection
arithSeqE,
fromR, fromThenR, fromToR, fromThenToR,
-- **** Statements
doE, compE,
bindS, letS, noBindS, parS,
-- *** Types
forallT, varT, conT, appT, arrowT, listT, tupleT, sigT,
-- **** Strictness
isStrict, notStrict, strictType, varStrictType,
cCall, stdCall, unsafe, safe, threadsafe,
inlineSpecNoPhase, inlineSpecPhase, typeFam, dataFam,
-- **** Class Contexts
cxt, classP, equalP, normalC, recC, infixC,
-- *** Top Level Declarations
-- **** Data
valD, funD, tySynD, dataD, newtypeD,
-- **** Class
classD, instanceD, sigD,
-- **** Type Family / Data Family
familyNoKindD, familyKindD, dataInstD,
newtypeInstD, tySynInstD,
typeFam, dataFam,
-- **** Foreign Function Interface (FFI)
cCall, stdCall, unsafe, safe, threadsafe, forImpD,
-- **** Pragmas
-- | Just inline supported so far
inlineSpecNoPhase, inlineSpecPhase,
pragInlD, pragSpecD,
-- Pretty-printer
-- * Pretty-printer
Ppr(..), pprint, pprExp, pprLit, pprPat, pprParendType
) where
......
-- |
-- TH.Lib contains lots of useful helper functions for
-- generating and manipulating Template Haskell terms
......@@ -10,7 +11,7 @@ import Language.Haskell.TH.Syntax
import Control.Monad( liftM, liftM2 )
----------------------------------------------------------
-- Type synonyms
-- * Type synonyms
----------------------------------------------------------
type InfoQ = Q Info
......@@ -35,7 +36,7 @@ type FieldExpQ = Q FieldExp
type InlineSpecQ = Q InlineSpec
----------------------------------------------------------
-- Lowercase pattern syntax functions
-- * Lowercase pattern syntax functions
----------------------------------------------------------
intPrimL :: Integer -> Lit
......@@ -96,7 +97,7 @@ fieldPat n p = do p' <- p
-------------------------------------------------------------------------------
-- Stmt
-- * Stmt
bindS :: PatQ -> ExpQ -> StmtQ
bindS p e = liftM2 BindS p e
......@@ -111,7 +112,7 @@ parS :: [[StmtQ]] -> StmtQ
parS _ = fail "No parallel comprehensions yet"
-------------------------------------------------------------------------------
-- Range
-- * Range
fromR :: ExpQ -> RangeQ
fromR x = do { a <- x; return (FromR a) }
......@@ -126,7 +127,7 @@ fromThenToR :: ExpQ -> ExpQ -> ExpQ -> RangeQ
fromThenToR x y z = do { a <- x; b <- y; c <- z;
return (FromThenToR a b c) }
-------------------------------------------------------------------------------
-- Body
-- * Body
normalB :: ExpQ -> BodyQ
normalB e = do { e1 <- e; return (NormalB e1) }
......@@ -135,7 +136,7 @@ guardedB :: [Q (Guard,Exp)] -> BodyQ
guardedB ges = do { ges' <- sequence ges; return (GuardedB ges') }
-------------------------------------------------------------------------------
-- Guard
-- * Guard
normalG :: ExpQ -> GuardQ
normalG e = do { e1 <- e; return (NormalG e1) }
......@@ -152,14 +153,16 @@ patGE ss e = do { ss' <- sequence ss;
return (PatG ss', e') }
-------------------------------------------------------------------------------
-- Match and Clause
-- * Match and Clause
-- | Use with 'caseE'
match :: PatQ -> BodyQ -> [DecQ] -> MatchQ
match p rhs ds = do { p' <- p;
r' <- rhs;
ds' <- sequence ds;
return (Match p' r' ds') }
-- | Use with 'funD'
clause :: [PatQ] -> BodyQ -> [DecQ] -> ClauseQ
clause ps r ds = do { ps' <- sequence ps;
r' <- r;
......@@ -168,8 +171,9 @@ clause ps r ds = do { ps' <- sequence ps;
---------------------------------------------------------------------------
-- Exp
-- * Exp
-- | Dynamically binding a variable (unhygenic)
dyn :: String -> Q Exp
dyn s = return (VarE (mkName s))
......@@ -209,7 +213,8 @@ lamE ps e = do ps' <- sequence ps
e' <- e
return (LamE ps' e')
lam1E :: PatQ -> ExpQ -> ExpQ -- Single-arg lambda
-- | Single-arg lambda
lam1E :: PatQ -> ExpQ -> ExpQ
lam1E p e = lamE [p] e
tupE :: [ExpQ] -> ExpQ
......@@ -233,21 +238,6 @@ compE ss = do { ss1 <- sequence ss; return (CompE ss1) }
arithSeqE :: RangeQ -> ExpQ
arithSeqE r = do { r' <- r; return (ArithSeqE r') }
-- arithSeqE Shortcuts
fromE :: ExpQ -> ExpQ
fromE x = do { a <- x; return (ArithSeqE (FromR a)) }
fromThenE :: ExpQ -> ExpQ -> ExpQ
fromThenE x y = do { a <- x; b <- y; return (ArithSeqE (FromThenR a b)) }
fromToE :: ExpQ -> ExpQ -> ExpQ
fromToE x y = do { a <- x; b <- y; return (ArithSeqE (FromToR a b)) }
fromThenToE :: ExpQ -> ExpQ -> ExpQ -> ExpQ
fromThenToE x y z = do { a <- x; b <- y; c <- z;
return (ArithSeqE (FromThenToR a b c)) }
-- End arithSeqE shortcuts
listE :: [ExpQ] -> ExpQ
listE es = do { es1 <- sequence es; return (ListE es1) }
......@@ -266,8 +256,23 @@ stringE = litE . stringL
fieldExp :: Name -> ExpQ -> Q (Name, Exp)
fieldExp s e = do { e' <- e; return (s,e') }
-- ** 'arithSeqE' Shortcuts
fromE :: ExpQ -> ExpQ
fromE x = do { a <- x; return (ArithSeqE (FromR a)) }
fromThenE :: ExpQ -> ExpQ -> ExpQ
fromThenE x y = do { a <- x; b <- y; return (ArithSeqE (FromThenR a b)) }
fromToE :: ExpQ -> ExpQ -> ExpQ
fromToE x y = do { a <- x; b <- y; return (ArithSeqE (FromToR a b)) }
fromThenToE :: ExpQ -> ExpQ -> ExpQ -> ExpQ
fromThenToE x y z = do { a <- x; b <- y; c <- z;
return (ArithSeqE (FromThenToR a b c)) }
-------------------------------------------------------------------------------
-- Dec
-- * Dec
valD :: PatQ -> BodyQ -> [DecQ] -> DecQ
valD p b ds =
......@@ -403,7 +408,7 @@ forallC ns ctxt con = liftM2 (ForallC ns) ctxt con
-------------------------------------------------------------------------------
-- Type
-- * Type
forallT :: [TyVarBndr] -> CxtQ -> TypeQ -> TypeQ
forallT tvars ctxt ty = do
......@@ -450,7 +455,7 @@ varStrictType v st = do (s, t) <- st
return (v, s, t)
-------------------------------------------------------------------------------
-- Kind
-- * Kind
plainTV :: Name -> TyVarBndr
plainTV = PlainTV
......@@ -465,14 +470,14 @@ arrowK :: Kind -> Kind -> Kind
arrowK = ArrowK
-------------------------------------------------------------------------------
-- Callconv
-- * Callconv
cCall, stdCall :: Callconv
cCall = CCall
stdCall = StdCall
-------------------------------------------------------------------------------
-- Safety
-- * Safety
unsafe, safe, threadsafe :: Safety
unsafe = Unsafe
......@@ -480,7 +485,7 @@ safe = Safe
threadsafe = Threadsafe
-------------------------------------------------------------------------------
-- InlineSpec
-- * InlineSpec
inlineSpecNoPhase :: Bool -> Bool -> InlineSpecQ
inlineSpecNoPhase inline conlike
......@@ -491,20 +496,20 @@ inlineSpecPhase inline conlike beforeFrom phase
= return $ InlineSpec inline conlike (Just (beforeFrom, phase))
-------------------------------------------------------------------------------
-- FunDep
-- * FunDep
funDep :: [Name] -> [Name] -> FunDep
funDep = FunDep
-------------------------------------------------------------------------------
-- FamFlavour
-- * FamFlavour
typeFam, dataFam :: FamFlavour
typeFam = TypeFam
dataFam = DataFam
--------------------------------------------------------------
-- Useful helper functions
-- * Useful helper functions
combine :: [([(Name, Name)], Pat)] -> ([(Name, Name)], [Pat])
combine pairs = foldr f ([],[]) pairs
......@@ -542,7 +547,7 @@ alpha env s = case lookup s env of
Nothing -> varE s
appsE :: [ExpQ] -> ExpQ
appsE [] = error "appsExp []"
appsE [] = error "appsE []"
appsE [x] = x
appsE (x:y:zs) = appsE ( (appE x y) : zs )
......
-- TH.Ppr contains a prettyprinter for the
-- | contains a prettyprinter for the
-- Template Haskell datatypes
module Language.Haskell.TH.Ppr where
......
-- Monadic front-end to Text.PrettyPrint.HughesPJ
-- | Monadic front-end to Text.PrettyPrint.HughesPJ
module Language.Haskell.TH.PprLib (
......
......@@ -26,11 +26,11 @@ module Language.Haskell.TH.Syntax(
report, recover, reify,
location, runIO,
-- Names
-- * Names
Name(..), mkName, newName, nameBase, nameModule,
showName, showName', NameIs(..),
-- The algebraic data types
-- * The algebraic data types
Dec(..), Exp(..), Con(..), Type(..), TyVarBndr(..), Kind(..),Cxt,
Pred(..), Match(..), Clause(..), Body(..), Guard(..), Stmt(..),
Range(..), Lit(..), Pat(..), FieldExp, FieldPat,
......@@ -39,7 +39,7 @@ module Language.Haskell.TH.Syntax(
Info(..), Loc(..), CharPos,
Fixity(..), FixityDirection(..), defaultFixity, maxPrecedence,
-- Internal functions
-- * Internal functions
returnQ, bindQ, sequenceQ,
NameFlavour(..), NameSpace (..),
mkNameG_v, mkNameG_d, mkNameG_tc, Uniq, mkNameL, mkNameU,
......@@ -67,21 +67,22 @@ import Data.Char ( isAlpha )
-----------------------------------------------------
class (Monad m, Functor m) => Quasi m where
-- Fresh names
qNewName :: String -> m Name
-- ^ Fresh names
-- Error reporting and recovery
qReport :: Bool -> String -> m () -- Report an error (True) or warning (False)
qReport :: Bool -> String -> m () -- ^ Report an error (True) or warning (False)
-- ...but carry on; use 'fail' to stop
qRecover :: m a -> m a -> m a -- Recover from the monadic 'fail'
-- The first arg is the error handler
qRecover :: m a -- ^ the error handler
-> m a -- ^ action which may fail
-> m a -- ^ Recover from the monadic 'fail'
-- Inspect the type-checker's environment
qReify :: Name -> m Info
qLocation :: m Loc
-- Input/output (dangerous)
qRunIO :: IO a -> m a
-- ^ Input/output (dangerous)
-----------------------------------------------------
......@@ -147,7 +148,9 @@ newName s = Q (qNewName s)
report :: Bool -> String -> Q ()
report b s = Q (qReport b s)
recover :: Q a -> Q a -> Q a
recover :: Q a -- ^ recover with this one
-> Q a -- ^ failing action
-> Q a
recover (Q r) (Q m) = Q (qRecover r m)
-- | 'reify' looks up information about the 'Name'
......@@ -311,39 +314,48 @@ occString (OccName occ) = occ
-- Names
-----------------------------------------------------
-- For "global" names (NameG) we need a totally unique 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
-- 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
-- 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 |]
--
-- > 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
data Name = Name OccName NameFlavour deriving (Typeable, Data)
data NameFlavour
= NameS -- An unqualified name; dynamically bound
| NameQ ModName -- A qualified name; dynamically bound
= NameS -- ^ An unqualified name; dynamically bound
| NameQ ModName -- ^ A qualified name; dynamically bound
| NameU Int# -- A unique local name
| NameU Int# -- ^ A unique local name
-- The next two are for lexically-scoped names that
-- are bound *outside* the TH syntax tree,
-- either globally (NameG) or locally (NameL)
-- e.g. 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
| NameL Int# --
| NameG NameSpace PkgName ModName -- An original name (occurrences only, not binders)
| 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
deriving ( Typeable )
-- |
-- 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
......@@ -386,14 +398,15 @@ ty_NameFlavour = mkDataType "Language.Haskell.TH.Syntax.NameFlavour"
[con_NameS, con_NameQ, con_NameU,
con_NameL, con_NameG]
data NameSpace = VarName -- Variables
| DataName -- Data constructors
| TcClsName -- Type constructors and classes; Haskell has them
data NameSpace = VarName -- ^ Variables
| DataName -- ^ Data constructors
| TcClsName -- ^ Type constructors and classes; Haskell has them
-- in the same name space for now.
deriving( Eq, Ord, Data, Typeable )
type Uniq = Int
-- | Base, unqualified name.
nameBase :: Name -> String
nameBase (Name occ _) = occString occ
......@@ -403,14 +416,16 @@ nameModule (Name _ (NameG _ _ m)) = Just (modString m)
nameModule _ = Nothing
mkName :: String -> Name
-- The string can have a '.', thus "Foo.baz",
-- ^ 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
--
-- > Foo.Baz.x as Qual Foo.Baz x
--
-- So we parse it from back to front
mkName str
= split [] (reverse str)
......@@ -427,14 +442,17 @@ mkName str
-- This rather bizarre case actually happened; (.&.) is in Data.Bits
split occ (c:rev) = split (c:occ) rev
mkNameU :: String -> Uniq -> Name -- Only used internally
-- | Only used internally
mkNameU :: String -> Uniq -> Name
mkNameU s (I# u) = Name (mkOccName s) (NameU u)
mkNameL :: String -> Uniq -> Name -- Only used internally
-- | Only used internally
mkNameL :: String -> Uniq -> Name
mkNameL s (I# u) = Name (mkOccName s) (NameL u)
mkNameG :: NameSpace -> String -> String -> String -> Name -- Used for 'x etc, but not available
mkNameG ns pkg modu occ -- to the programmer
-- | Used for 'x etc, but not available to the programmer
mkNameG :: NameSpace -> String -> String -> String -> Name
mkNameG ns pkg modu occ
= Name (mkOccName occ) (NameG ns (mkPkgName pkg) (mkModName modu))
mkNameG_v, mkNameG_tc, mkNameG_d :: String -> String -> String -> Name
......@@ -525,8 +543,8 @@ instance Show Name where
show = showName
-- Tuple data and type constructors
tupleDataName :: Int -> Name -- Data constructor
tupleTypeName :: Int -> Name -- Type constructor
tupleDataName :: Int -> Name -- ^ Data constructor
tupleTypeName :: Int -> Name -- ^ Type constructor
tupleDataName 0 = mk_tup_name 0 DataName
tupleDataName 1 = error "tupleDataName 1"
......@@ -566,7 +584,8 @@ type CharPos = (Int, Int) -- Line and character position
--
-----------------------------------------------------
data Info
-- | Obtained from 'reify' in the 'Q' Monad.
data Info
= ClassI Dec
| ClassOpI
Name -- The class op itself
......@@ -621,7 +640,7 @@ defaultFixity = Fixity maxPrecedence InfixL
data Lit = CharL Char
| StringL String
| IntegerL Integer -- Used for overloaded and non-overloaded
| 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?
......@@ -636,60 +655,65 @@ data Lit = CharL Char
-- but that could complicate the
-- suppposedly-simple TH.Syntax literal type
-- | Pattern in Haskell given in @{}@
data Pat
= 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 }
= 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 }@
deriving( Show, Eq, Data, Typeable )
type FieldPat = (Name,Pat)
data Match = Match Pat Body [Dec]
-- case e of { pat -> body where decs }
data Match = Match Pat Body [Dec] -- ^ @case e of { pat -> body where decs }@
deriving( Show, Eq, Data, Typeable )
data Clause = Clause [Pat] Body [Dec]
-- f { p1 p2 = body where decs }
-- ^ @f { p1 p2 = body where decs }@
deriving( Show, Eq, Data, Typeable )
-- | 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. [ f x | x <- xs ] is represented by
-- CompE [BindS (VarP x) (VarE xs), NoBindS (AppE (VarE f) (VarE x))]
--
-- E.g. translation:
--
-- > [ f x | x <- xs ]
--
-- > CompE [BindS (VarP x) (VarE xs), NoBindS (AppE (VarE f) (VarE x))]
data Exp
= VarE Name -- { x }