git.iko.soy/haskell-generate
on master help sign in
Refactor and add tutorial to README.md
commitc129f0625c04166fd73869243ee0c17b107092b8 authorBenno Fünfstück <benno.fuenfstueck@gmail.com> dateMon 23 Dec 2013, 16:32 (13 years ago) parent14fa497
7 files changed+188−63
README.md+100−1 haskell-generate.cabal+2−1 src/Language/Haskell/Generate.hs+2−1 src/Language/Haskell/Generate/Expression.hs+12 src/Language/Haskell/Generate/Base.hs → src/Language/Haskell/Generate/Monad.hs+58−50 src/Language/Haskell/Generate/PreludeDef.hs+8−8 src/Language/Haskell/Generate/TH.hs+6−2
README.md+100−1
@@ -1,6 +1,105 @@
11haskell-generate
2−====================
2+================
33
44[![Build Status](https://secure.travis-ci.org/bennofs/haskell-generate.png?branch=master)](http://travis-ci.org/bennofs/haskell-generate)
55
6+## Introduction
7+
8+If you want to generate haskell source code, you could build up haskell-src-exts AST and then pretty print it. But that's easy to screw up, because haskell-src-exts doesn't include tag it's AST with a type. This library aims to fill the gap, adding type information to haskell-src-exts expressions and also managing imports for you.
9+
10+## Getting started
11+
12+First, you need to import this library:
13+
14+```haskell
15+import Language.Haskell.Generate
16+```
17+
18+This module reexports `Language.Haskell.Exts.Syntax`, because haskell-generate builds on top of that.
19+
20+There are two main types in haskell-generate. The first is the monad `Generate` and the type alias `ExpG`. The `Generate` monad is used to track required imports. It also allows to generate unique names. `ExpG t` is just an action in the `Generate` monad that returns an expression of type `t`.
21+
22+How do you build expressions? There is a number of predefined expressions for the functions in the
23+Prelude. This allows you to just use these and combine them to new expressions. For example, let's define a expression that reads a file called "names":
24+
25+```haskell
26+readNamesFile' :: ExpG (IO String)
27+readNamesFile' = readFile' <>$ expr "names"
28+```
29+
30+Here we use `(<>$)` to apply the `readFile'` expression to the string `names`. `readFile'` is one of the expressions already provided by haskell-generate. All expressions that are provided by haskell-generate end with an apostrophe. You can find more of them in the module `Language.Haskell.Generate.PreludeDef`. The `expr` function is used to lift the string `names` into an expression of type `ExpG String`.
31+
32+Now that we have an expression, we need to bind it to a name in a module. For this job, we use another monad, the `ModuleM` monad. It allows you to bind expressions to names and then generate
33+a module with those names.
34+
35+Here's how we generate our module:
36+
37+```haskell
38+myModule :: ModuleG
39+myModule = do
40+ d <- addDecl (Ident "main") $ applyE2 bind' readNamesFile' putStrLn'
41+ return $ Just [exportFun d]
42+```
43+
44+`ModuleG` is again a type synonym for an action in the `ModuleM` monad. It must either return Nothing (which omits the export list) or an export list. In this case, we export the "main" function, which we previously defined using `addDecl`.
45+
46+The only thing left to do is to generate the actual source code for the module, for which we
47+use the `generateModule` function, which takes the module name as an argument:
48+
49+```haskell
50+main :: IO ()
51+main = putStrLn $ generateModule myModule "Main"
52+```
53+
54+If you run the program, you'll get the following output:
55+
56+```haskell
57+module Main (main) where
58+import qualified GHC.Base
59+import qualified System.IO
60+main
61+ = (GHC.Base.>>=) (System.IO.readFile ['n', 'a', 'm', 'e', 's'])
62+ System.IO.putStrLn
63+```
64+
65+If you run this code, you'll get the contents of the "names" file. The code is a bit ugly and uses
66+qualified imports to avoid name clashes, but it works.
67+
68+## Importing functions
69+
70+Until now, we've only used the predefined expressions from `Language.Haskell.Generate.PreludeDef`, but often you'll want to use definitions from other modules that you might want to use.
71+
72+You can do that using the `useValue` from haskell-generate. Let's look at the type of `useValue`:
73+
74+```haskell
75+useValue :: String -> Name -> ExpG t
76+```
77+
78+`useValue` takes a module name in which the function is defined and the name of the function. It returns an expression of any type you which. This function is unsafe, because it cannot check that the returned type is actually the type of the function. That's why you usually given `useValue` an explicit type signature.
79+
80+For example, suppose we want to use the function `permutations` from Data.List. We write the following definition for it:
81+
82+```haskell
83+permutations' :: ExpG ([a] -> [[a]]) -- Here we given an explicit type for permutations'. This is not checked, so make sure it's actually right!
84+permutations' = useValue "Data.List" (Ident "permutations") -- "permutations" is an identifier, not a symbol, so we use the "Ident" constructor.
85+```
86+
87+## Using TH to automagically import functions
88+
89+If the function you want to import is already available at compile time, you can use the template haskell code from `Language.Haskell.Generate.TH` to generate the expression definitions. This is the approach we use for the Prelude, as an example.
90+
91+Using the example from the previous section, we could also import the `permutations` function like this:
92+
93+```haskell
94+-- at the top of the file:
95+{-# LANGUAGE TemplateHaskell #-} -- Enable template haskell
96+import Data.List (permutations) -- The function needs to be available at compile time
97+
98+declareFunction 'permutations -- This generates the same code as above, but is more type-safe because you don't have to specify the type yourself.
99+```
100+
101+
102+## Contributing
103+
104+If you have an idea, a question or a bug report, open an issue on github. You can also find me on freenode in the #haskell channel, my nick is bennofs.
6105
haskell-generate.cabal+2−1
@@ -37,7 +37,8 @@ library
3737 , template-haskell
3838 exposed-modules:
3939 Language.Haskell.Generate
40− Language.Haskell.Generate.Base
40+ Language.Haskell.Generate.Monad
41+ Language.Haskell.Generate.Expression
4142 Language.Haskell.Generate.TH
4243 Language.Haskell.Generate.PreludeDef
4344
src/Language/Haskell/Generate.hs+2−1
@@ -2,5 +2,6 @@ module Language.Haskell.Generate
22 ( module X
33 ) where
44
5−import Language.Haskell.Generate.Base as X
5+import Language.Haskell.Exts.Syntax as X
6+import Language.Haskell.Generate.Monad as X
67import Language.Haskell.Generate.PreludeDef as X
src/Language/Haskell/Generate/Expression.hsnew file+12
@@ -0,0 +1,12 @@
1+module Language.Haskell.Generate.Expression
2+ ( Expression(..)
3+ , app
4+ ) where
5+
6+import Language.Haskell.Exts.Syntax
7+
8+newtype Expression t = Expression { runExpression :: Exp }
9+
10+app :: Expression (a -> b) -> Expression a -> Expression b
11+app (Expression a) (Expression b) = Expression $ App a b
12+
src/Language/Haskell/Generate/Base.hs → src/Language/Haskell/Generate/Monad.hsrenamed+58−50
@@ -3,9 +3,10 @@
33{-# LANGUAGE ScopedTypeVariables #-}
44{-# LANGUAGE UndecidableInstances #-}
55{-# LANGUAGE FlexibleInstances #-}
6−module Language.Haskell.Generate.Base
7− ( ExpM(..), ExpG, ExpType
8− , runExpM, newName
6+module Language.Haskell.Generate.Monad
7+ ( Generate(..), ExpG
8+ , runGenerate, newName
9+ , returnE
910 , useValue, useCon, useVar
1011 , caseE
1112 , applyE, applyE2, applyE3, applyE4, applyE5, applyE6
@@ -19,6 +20,7 @@ module Language.Haskell.Generate.Base
1920 , addDecl
2021 , runModuleM
2122 , generateModule
23+ , generateExp
2224 )
2325 where
2426
@@ -31,32 +33,30 @@ import qualified Data.Set as S
3133import Language.Haskell.Exts.Pretty
3234import Language.Haskell.Exts.SrcLoc
3335import Language.Haskell.Exts.Syntax
36+import Language.Haskell.Generate.Expression
3437
3538--------------------------------------------------------------------------------
3639-- Generate expressions
3740
38−-- | A ExpM is a monad used to track the imports that are needed for a given expression. Usually, you don't have to use
39−-- this type directly, but use combinators to combine several ExpM into bigger expressions. The t type parameter tracks
40−-- the type of the expression, so you don't accidently build expression that don't type check.
41−newtype ExpM t a = ExpM { unExpM :: StateT Integer (Writer (S.Set ModuleName)) a } deriving (Functor, Applicative, Monad)
41+newtype Generate a = Generate { unGenerate :: StateT Integer (Writer (S.Set ModuleName)) a } deriving (Functor, Applicative, Monad)
4242
43−-- | The ExpG type is a ExpM computation that returns an expression. Usually, this is the end result of a function generating
44−-- a haskell expression
45−type ExpG t = ExpM t Exp
43+runGenerate :: Generate a -> (a, S.Set ModuleName)
44+runGenerate (Generate a) = runWriter $ evalStateT a 0
4645
47−-- | Evaluate a ExpM action, returning the needed modules and the value.
48−runExpM :: ExpM t a -> (a, S.Set ModuleName)
49−runExpM (ExpM expt) = runWriter $ evalStateT expt 0
46+type ExpG t = Generate (Expression t)
5047
51−unsafeCoerceE :: ExpM t a -> ExpM t' a
52−unsafeCoerceE (ExpM x) = ExpM x
48+returnE :: Exp -> ExpG t
49+returnE = return . Expression
50+
51+generateExp :: ExpG t -> String
52+generateExp = prettyPrint . runExpression . fst . runGenerate
5353
5454-- | Generate a case expression.
5555caseE :: ExpG x -> [(Pat, ExpG t)] -> ExpG t
5656caseE v alt = do
57− v' <- unsafeCoerceE v
58− alt' <- mapM (\(p,a) -> fmap (\a' -> Alt noLoc p (UnGuardedAlt a') (BDecls [])) a) alt
59− return $ Case v' alt'
57+ v' <- v
58+ alt' <- mapM (\(p,a) -> fmap (\a' -> Alt noLoc p (UnGuardedAlt $ runExpression a') (BDecls [])) a) alt
59+ return $ Expression $ Case (runExpression v') alt'
6060
6161-- | Import a function from a module. This function is polymorphic in the type of the resulting expression,
6262-- you should probably only use this function to define type-restricted specializations.
@@ -67,31 +67,27 @@ caseE v alt = do
6767-- > addInt = useValue "Prelude" $ Symbol "+"
6868--
6969useValue :: String -> Name -> ExpG a
70−useValue md name = ExpM $ do
70+useValue md name = Generate $ do
7171 lift $ tell $ S.singleton $ ModuleName md
72− return $ Var $ Qual (ModuleName md) name
72+ return $ Expression $ Var $ Qual (ModuleName md) name
7373
7474-- | Import a value constructor from a module. Returns the qualified name of the constructor.
75−useCon :: String -> Name -> ExpM t QName
76−useCon md name = ExpM $ do
75+useCon :: String -> Name -> Generate QName
76+useCon md name = Generate $ do
7777 lift $ tell $ S.singleton $ ModuleName md
7878 return $ Qual (ModuleName md) name
7979
8080-- | Use the value of a variable with the given name.
8181useVar :: Name -> ExpG t
82−useVar name = return $ Var $ UnQual name
82+useVar name = return $ Expression $ Var $ UnQual name
8383
8484-- | Generate a new unique variable name with the given prefix. Note that this new variable name
8585-- is only unique relative to other variable names generated by this function.
86−newName :: String -> ExpM t Name
87−newName pref = ExpM $ do
86+newName :: String -> Generate Name
87+newName pref = Generate $ do
8888 i <- get <* modify succ
8989 return $ Ident $ pref ++ show i
9090
91−-- | This type family can be used to get the type associated with some expression.
92−type family ExpType a :: *
93−type instance ExpType (ExpM t a) = t
94−
9591-- | Generate a expression from a haskell value.
9692class GenExp t where
9793 type GenExpType t :: *
@@ -103,36 +99,43 @@ instance GenExp (ExpG a) where
10399 type GenExpType (ExpG a) = a
104100 expr = id
105101
102+instance GenExp (Expression t) where
103+ type GenExpType (Expression t) = t
104+ expr = return
105+
106106instance GenExp Char where
107107 type GenExpType Char = Char
108− expr = return . Lit . Char
108+ expr = return . Expression . Lit . Char
109109
110110instance GenExp Integer where
111111 type GenExpType Integer = Integer
112− expr = return . Lit . Int
112+ expr = return . Expression . Lit . Int
113113
114114instance GenExp Rational where
115115 type GenExpType Rational = Rational
116− expr = return . Lit . Frac
116+ expr = return . Expression . Lit . Frac
117117
118118instance GenExp a => GenExp [a] where
119119 type GenExpType [a] = [GenExpType a]
120− expr = ExpM . fmap List . mapM (unExpM . expr)
120+ expr = Generate . fmap (Expression . List . map runExpression) . mapM (unGenerate . expr)
121121
122122instance GenExp x => GenExp (ExpG a -> x) where
123123 type GenExpType (ExpG a -> x) = a -> GenExpType x
124124 expr f = do
125125 pvarName <- newName "pvar_"
126− body <- unsafeCoerceE $ expr $ f $ return $ Var $ UnQual pvarName
127− return $ Lambda noLoc [PVar pvarName] body
126+ body <- expr $ f $ return $ Expression $ Var $ UnQual pvarName
127+ return $ Expression $ Lambda noLoc [PVar pvarName] $ runExpression body
128128
129129--------------------------------------------------------------------------------
130130-- Apply functions
131131
132+
132133-- | Apply a function in a haskell expression to a value.
133134applyE :: ExpG (a -> b) -> ExpG a -> ExpG b
134−applyE a b = unsafeCoerceE $ liftM (foldl1 App) $ sequence [ce a,ce b]
135− where ce = unsafeCoerceE
135+applyE a b = wrap $ liftM (foldl1 App) $ sequence [unwrap a, unwrap b]
136+ where wrap = fmap Expression
137+ unwrap = fmap runExpression
138+
136139
137140-- | Operator for 'applyE'.
138141(<>$) :: ExpG (a -> b) -> ExpG a -> ExpG b
@@ -142,28 +145,33 @@ infixl 1 <>$
142145
143146-- | ApplyE for 2 arguments
144147applyE2 :: ExpG (a -> b -> c) -> ExpG a -> ExpG b -> ExpG c
145−applyE2 a b c = unsafeCoerceE $ liftM (foldl1 App) $ sequence [ce a,ce b,ce c]
146− where ce = unsafeCoerceE
148+applyE2 a b c = wrap $ liftM (foldl1 App) $ sequence [unwrap a,unwrap b,unwrap c]
149+ where wrap = fmap Expression
150+ unwrap = fmap runExpression
147151
148152-- | Apply a function to 3 arguments
149153applyE3 :: ExpG (a -> b -> c -> d) -> ExpG a -> ExpG b -> ExpG c -> ExpG d
150−applyE3 a b c d = unsafeCoerceE $ liftM (foldl1 App) $ sequence [ce a,ce b,ce c,ce d]
151− where ce = unsafeCoerceE
154+applyE3 a b c d = wrap $ liftM (foldl1 App) $ sequence [unwrap a,unwrap b,unwrap c,unwrap d]
155+ where wrap = fmap Expression
156+ unwrap = fmap runExpression
152157
153158-- | Apply a function to 4 arguments
154159applyE4 :: ExpG (a -> b -> c -> d -> e) -> ExpG a -> ExpG b -> ExpG c -> ExpG d -> ExpG e
155−applyE4 a b c d e = unsafeCoerceE $ liftM (foldl1 App) $ sequence [ce a,ce b,ce c,ce d,ce e]
156− where ce = unsafeCoerceE
160+applyE4 a b c d e = wrap $ liftM (foldl1 App) $ sequence [unwrap a,unwrap b,unwrap c,unwrap d,unwrap e]
161+ where wrap = fmap Expression
162+ unwrap = fmap runExpression
157163
158164-- | Apply a function to 5 arguments
159165applyE5 :: ExpG (a -> b -> c -> d -> e -> f) -> ExpG a -> ExpG b -> ExpG c -> ExpG d -> ExpG e -> ExpG f
160−applyE5 a b c d e f = unsafeCoerceE $ liftM (foldl1 App) $ sequence [ce a,ce b,ce c,ce d,ce e,ce f]
161− where ce = unsafeCoerceE
166+applyE5 a b c d e f = wrap $ liftM (foldl1 App) $ sequence [unwrap a,unwrap b,unwrap c,unwrap d,unwrap e,unwrap f]
167+ where wrap = fmap Expression
168+ unwrap = fmap runExpression
162169
163170-- | Apply a function to 6 arguments
164171applyE6 :: ExpG (a -> b -> c -> d -> e -> f -> g) -> ExpG a -> ExpG b -> ExpG c -> ExpG d -> ExpG e -> ExpG f -> ExpG g
165−applyE6 a b c d e f g = unsafeCoerceE $ liftM (foldl1 App) $ sequence [ce a,ce b,ce c,ce d,ce e,ce f,ce g]
166− where ce = unsafeCoerceE
172+applyE6 a b c d e f g = wrap $ liftM (foldl1 App) $ sequence [unwrap a,unwrap b,unwrap c,unwrap d,unwrap e,unwrap f,unwrap g]
173+ where wrap = fmap Expression
174+ unwrap = fmap runExpression
167175
168176--------------------------------------------------------------------------------
169177-- Generate modules
@@ -180,7 +188,7 @@ data FunRef t = FunRef Name
180188
181189instance GenExp (FunRef t) where
182190 type GenExpType (FunRef t) = t
183− expr (FunRef n) = return $ Var $ UnQual n
191+ expr (FunRef n) = return $ Expression $ Var $ UnQual n
184192
185193-- | Generate a ExportSpec for a given function item.
186194exportFun :: FunRef t -> ExportSpec
@@ -189,8 +197,8 @@ exportFun (FunRef name) = EVar (UnQual name)
189197-- | Add a declaration to the module. Return a reference to it that can be used to either apply the function to some values or export it.
190198addDecl :: Name -> ExpG t -> ModuleM (FunRef t)
191199addDecl name e = ModuleM $ do
192− let (body, mods) = runExpM e
193− tell (mods, [FunBind [Match noLoc name [] Nothing (UnGuardedRhs body) $ BDecls []]])
200+ let (body, mods) = runGenerate e
201+ tell (mods, [FunBind [Match noLoc name [] Nothing (UnGuardedRhs $ runExpression body) $ BDecls []]])
194202 return $ FunRef name
195203
196204-- | Extract the Module from a module generator.
src/Language/Haskell/Generate/PreludeDef.hs+8−8
@@ -6,7 +6,7 @@
66module Language.Haskell.Generate.PreludeDef where
77
88import Language.Haskell.Exts.Syntax
9−import Language.Haskell.Generate.Base
9+import Language.Haskell.Generate.Monad
1010import Language.Haskell.Generate.TH
1111
1212--------------------------------------------------------------------------------
@@ -66,22 +66,22 @@ fmap concat $ mapM declareNamedSymbol
6666(<>.) a b = dot' <>$ a <>$ b
6767
6868tuple0 :: ExpG ()
69−tuple0 = return $ Var $ Special UnitCon
69+tuple0 = returnE $ Var $ Special UnitCon
7070
7171tuple2 :: ExpG (a -> b -> (a,b))
72−tuple2 = return $ Var $ Special $ TupleCon Boxed 2
72+tuple2 = returnE $ Var $ Special $ TupleCon Boxed 2
7373
7474tuple3 :: ExpG (a -> b -> c -> (a,b,c))
75−tuple3 = return $ Var $ Special $ TupleCon Boxed 3
75+tuple3 = returnE $ Var $ Special $ TupleCon Boxed 3
7676
7777tuple4 :: ExpG (a -> b -> c -> d -> (a,b,c,d))
78−tuple4 = return $ Var $ Special $ TupleCon Boxed 4
78+tuple4 = returnE $ Var $ Special $ TupleCon Boxed 4
7979
8080tuple5 :: ExpG (a -> b -> c -> d -> (a,b,c,d,e))
81−tuple5 = return $ Var $ Special $ TupleCon Boxed 5
81+tuple5 = returnE $ Var $ Special $ TupleCon Boxed 5
8282
8383cons :: ExpG (a -> [a] -> [a])
84−cons = return $ Var $ Special Cons
84+cons = returnE $ Var $ Special Cons
8585
8686instance Num t => Num (ExpG t) where
8787 a + b = add' <>$ a <>$ b
@@ -89,6 +89,6 @@ instance Num t => Num (ExpG t) where
8989 a * b = mult' <>$ a <>$ b
9090 negate a = negate' <>$ a
9191 abs a = abs' <>$ a
92− fromInteger a = return $ Lit $ Int a
92+ fromInteger a = returnE $ Lit $ Int a
9393 signum a = signum' <>$ a
9494
src/Language/Haskell/Generate/TH.hs+6−2
@@ -10,7 +10,7 @@ module Language.Haskell.Generate.TH
1010
1111import Data.Char
1212import Language.Haskell.Exts.Syntax hiding (Name)
13−import Language.Haskell.Generate.Base hiding (Name)
13+import Language.Haskell.Generate.Monad hiding (Name)
1414import Language.Haskell.TH
1515import Language.Haskell.TH.Syntax
1616
@@ -36,9 +36,13 @@ declareNamedThing (thing, name, thingClass) = do
3636 [| useValue $(lift md) $ $(conE thingClass) $(lift $ nameBase thing) |]
3737 ]
3838
39− where overQuantifiedType f (ForallT bnds ctx t) = ForallT bnds ctx $ overQuantifiedType f t
39+ where overQuantifiedType f (ForallT bnds ctx t) = ForallT (map removeKind bnds) ctx $ overQuantifiedType f t
4040 overQuantifiedType f x = f x
4141
42+ removeKind :: TyVarBndr -> TyVarBndr
43+ removeKind (KindedTV n _) = PlainTV n
44+ removeKind x = x
45+
4246-- | Declare a symbol, using the given name for the definition.
4347declareNamedSymbol :: (Name, String) -> DecsQ
4448declareNamedSymbol (func, name) = declareNamedThing (func, name, 'Symbol)