Base module for AntiQuoters, defining some basic type-aliases and and combinators for antiquoting.

To for examples in the documentation of this library the following data types defining the untyped lambda calculus syntax:

data Expr
    = VarE Var
    | Lam  Var Expr
    | App  Expr Expr
    | AntiExpr String
    deriving (Typeable, Data)
data Var
    = Var     String
    | AntiVar String
    deriving (Typeable, Data)

(note: the idea for using lambda calculus comes from the original paper on quasi-quoting http://www.eecs.harvard.edu/~mainland/ghc-quasiquoting/mainland07quasiquoting.pdf)

A simple quasi-quoter without support for antiquoting can be defined by:

lExp = QuasiQuoter
    { quoteExp  = dataToExpQ (const Nothing) . parseExpr
    , quotePat  = dataToPatQ (const Nothing) . parseExpr
    , quoteType = error "No type quoter"
    , quoteDec  = error "No declaration quoter"
    }
parseExpr :: String -> Expr
parseExpr = undefined -- implementation omitted

Now to add antiquoting it is needed to treat the AntiExpr and AntiVar constructors as special and translate them ourselves. This introduces an AntiQuoterPass e p, which is a specific translation rule from source syntax e to template haskell type p. In the example this can be used to defined:

antiExprE :: AntiQuoterPass Expr Exp
antiExprE (AntiExpr s) = Just . varE $ mkName s
antiExprE _            = Nothing
antiVarE :: AntiQuoterPass Var Exp
antiVarE (AntiVar s) = Just . varE $ mkName s
antiVarE _           = Nothing

antiExprP :: AntiQuoterPass Expr Pat
antiExprP (AntiExpr s) = Just . varP $ mkName s
antiExprP _            = Nothing
antiVarP :: AntiQuoterPass Var Pat
antiVarP (AntiVar s) = Just . varP $ mkName s
antiVarP _           = Nothing

Both rules should be used when antiquoting as an exception to the base case (using the default translation, const Nothing). Which can be done using (<>>), creating an AntiQuoter. Where an AntiQuoter represents a combination of AntiQuoterPasses which can be used to antiquote multiple datatypes. In the example this would result in

lExp = QuasiQuoter
    { quoteExp  = dataToExpQ antiE . parseExpr
    , quotePat  = dataToPatQ antiP . parseExpr
    , quoteType = error "No type quoter"
    , quoteDec  = error "No declaration quoter"
    }
    where
        antiE :: AntiQuoter Exp
        antiE = antiExprE <>> antiVarE <>> const Nothing
        antiP :: AntiQuoter Pat
        antiP = antiExprP <>> antiVarP <>> const Nothing

Two little improvements could be made, const Nothing could be replaced by noAntiQuoter and the building of the QuasiQuoter could be simplified by using mkQuasiQuoter.

WARNING: when combining AntiQuoter(Pass)es using extQ only the last (rightmost) pass will be used for any source type. The <<> and <>> don't suffer from this problem.