a8c59cce65a27215f2cd53b1f7fe747b346ca972
[packages/random.git] / Data / Generics / Aliases.hs
1 -----------------------------------------------------------------------------
2 -- |
3 -- Module : Data.Generics.Aliases
4 -- Copyright : (c) The University of Glasgow, CWI 2001--2003
5 -- License : BSD-style (see the file libraries/base/LICENSE)
6 --
7 -- Maintainer : libraries@haskell.org
8 -- Stability : experimental
9 -- Portability : non-portable
10 --
11 -- \"Scrap your boilerplate\" --- Generic programming in Haskell
12 -- See <http://www.cs.vu.nl/boilerplate/>. The present module provides
13 -- a number of declarations for typical generic function types,
14 -- corresponding type case, and others.
15 --
16 -----------------------------------------------------------------------------
17
18 module Data.Generics.Aliases (
19
20 -- * Combinators to \"make\" generic functions via cast
21 mkT, mkQ, mkM, mkMp, mkR,
22 extT, extQ, extM, extMp, extB, extR,
23
24 -- * Type synonyms for generic function types
25 GenericT,
26 GenericQ,
27 GenericM,
28 GenericB,
29 GenericR,
30 Generic,
31 Generic'(..),
32 GenericT'(..),
33 GenericQ'(..),
34 GenericM'(..),
35
36 -- * Inredients of generic functions
37 orElse,
38
39 -- * Function combinators on generic functions
40 recoverMp,
41 recoverQ,
42 choiceMp,
43 choiceQ,
44
45 -- * Operators for (over-appreciated) unfolding
46 gunfoldB,
47 gunfoldR
48
49 ) where
50
51 #ifdef __HADDOCK__
52 import Prelude
53 #endif
54 import Control.Monad
55 import Data.Generics.Basics
56
57 ------------------------------------------------------------------------------
58 --
59 -- Combinators to "make" generic functions
60 -- We use type-safe cast in a number of ways to make generic functions.
61 --
62 ------------------------------------------------------------------------------
63
64 -- | Make a generic transformation;
65 -- start from a type-specific case;
66 -- preserve the term otherwise
67 --
68 mkT :: ( Typeable a
69 , Typeable b
70 )
71 => (b -> b)
72 -> a
73 -> a
74 mkT f = case cast f of
75 Just g -> g
76 Nothing -> id
77
78
79 -- | Make a generic query;
80 -- start from a type-specific case;
81 -- return a constant otherwise
82 --
83 mkQ :: ( Typeable a
84 , Typeable b
85 )
86 => r
87 -> (b -> r)
88 -> a
89 -> r
90 (r `mkQ` br) a = case cast a of
91 Just b -> br b
92 Nothing -> r
93
94
95 -- | Make a generic monadic transformation;
96 -- start from a type-specific case;
97 -- resort to return otherwise
98 --
99 mkM :: ( Monad m
100 , Typeable a
101 , Typeable b
102 )
103 => (b -> m b)
104 -> a
105 -> m a
106 mkM f = case castarr f of
107 Just g -> g
108 Nothing -> return
109
110
111 {-
112
113 For the remaining definitions, we stick to a more concise style, i.e.,
114 we fold maybies with "maybe" instead of case ... of ..., and we also
115 use a point-free style whenever possible.
116
117 -}
118
119
120 -- | Make a generic monadic transformation for MonadPlus;
121 -- use \"const mzero\" (i.e., failure) instead of return as default.
122 --
123 mkMp :: ( MonadPlus m
124 , Typeable a
125 , Typeable b
126 )
127 => (b -> m b)
128 -> a
129 -> m a
130 mkMp = maybe (const mzero) id . castarr
131
132
133 -- | Make a generic builder;
134 -- start from a type-specific ase;
135 -- resort to no build (i.e., mzero) otherwise
136 --
137 mkR :: ( MonadPlus m
138 , Typeable a
139 , Typeable b
140 )
141 => m b -> m a
142 mkR = maybe mzero id . castss
143
144
145 -- | Extend a generic transformation by a type-specific case
146 extT :: ( Typeable a
147 , Typeable b
148 )
149 => (a -> a)
150 -> (b -> b)
151 -> a
152 -> a
153 extT f = maybe f id . cast
154
155
156 -- | Extend a generic query by a type-specific case
157 extQ :: ( Typeable a
158 , Typeable b
159 )
160 => (a -> q)
161 -> (b -> q)
162 -> a
163 -> q
164 extQ f g a = maybe (f a) g (cast a)
165
166
167 -- | Extend a generic monadic transformation by a type-specific case
168 extM :: ( Monad m
169 , Typeable a
170 , Typeable b
171 )
172 => (a -> m a) -> (b -> m b) -> a -> m a
173 extM f = maybe f id . castarr
174
175
176 -- | Extend a generic MonadPlus transformation by a type-specific case
177 extMp :: ( MonadPlus m
178 , Typeable a
179 , Typeable b
180 )
181 => (a -> m a) -> (b -> m b) -> a -> m a
182 extMp = extM
183
184
185 -- | Extend a generic builder
186 extB :: ( Typeable a
187 , Typeable b
188 )
189 => a -> b -> a
190 extB a = maybe a id . cast
191
192
193 -- | Extend a generic reader
194 extR :: ( Monad m
195 , Typeable a
196 , Typeable b
197 )
198 => m a -> m b -> m a
199 extR f = maybe f id . castss
200
201
202 ------------------------------------------------------------------------------
203 --
204 -- Type synonyms for generic function types
205 --
206 ------------------------------------------------------------------------------
207
208
209 -- | Generic transformations,
210 -- i.e., take an \"a\" and return an \"a\"
211 --
212 type GenericT = forall a. Data a => a -> a
213
214
215 -- | Generic queries of type \"r\",
216 -- i.e., take any \"a\" and return an \"r\"
217 --
218 type GenericQ r = forall a. Data a => a -> r
219
220
221 -- | Generic monadic transformations,
222 -- i.e., take an \"a\" and compute an \"a\"
223 --
224 type GenericM m = forall a. Data a => a -> m a
225
226
227 -- | Generic builders
228 -- i.e., produce an \"a\".
229 --
230 type GenericB = forall a. Data a => a
231
232
233 -- | Generic readers, say monadic builders,
234 -- i.e., produce an \"a\" with the help of a monad \"m\".
235 --
236 type GenericR m = forall a. Data a => m a
237
238
239 -- | The general scheme underlying generic functions
240 -- assumed by gfoldl; there are isomorphisms such as
241 -- GenericT = Generic ID.
242 --
243 type Generic c = forall a. Data a => a -> c a
244
245
246 -- | Wrapped generic functions;
247 -- recall: [Generic c] would be legal but [Generic' c] not.
248 --
249 data Generic' c = Generic' { unGeneric' :: Generic c }
250
251
252 -- | Other first-class polymorphic wrappers
253 newtype GenericT' = GenericT' { unGenericT' :: Data a => a -> a }
254 newtype GenericQ' r = GenericQ' { unGenericQ' :: GenericQ r }
255 newtype GenericM' m = GenericM' { unGenericM' :: Data a => a -> m a }
256
257
258 -- | Left-biased choice on maybies
259 orElse :: Maybe a -> Maybe a -> Maybe a
260 x `orElse` y = case x of
261 Just _ -> x
262 Nothing -> y
263
264
265 {-
266
267 The following variations take "orElse" to the function
268 level. Furthermore, we generalise from "Maybe" to any
269 "MonadPlus". This makes sense for monadic transformations and
270 queries. We say that the resulting combinators modell choice. We also
271 provide a prime example of choice, that is, recovery from failure. In
272 the case of transformations, we recover via return whereas for
273 queries a given constant is returned.
274
275 -}
276
277 -- | Choice for monadic transformations
278 choiceMp :: MonadPlus m => GenericM m -> GenericM m -> GenericM m
279 choiceMp f g x = f x `mplus` g x
280
281
282 -- | Choice for monadic queries
283 choiceQ :: MonadPlus m => GenericQ (m r) -> GenericQ (m r) -> GenericQ (m r)
284 choiceQ f g x = f x `mplus` g x
285
286
287 -- | Recover from the failure of monadic transformation by identity
288 recoverMp :: MonadPlus m => GenericM m -> GenericM m
289 recoverMp f = f `choiceMp` return
290
291
292 -- | Recover from the failure of monadic query by a constant
293 recoverQ :: MonadPlus m => r -> GenericQ (m r) -> GenericQ (m r)
294 recoverQ r f = f `choiceQ` const (return r)
295
296
297
298 ------------------------------------------------------------------------------
299 --
300 -- Generic unfolding
301 --
302 ------------------------------------------------------------------------------
303
304 -- | Construct an initial term with undefined immediate subterms
305 -- and then map over the skeleton to fill in proper terms.
306 gunfoldB :: Data a
307 => Constr
308 -> (forall a. Data a => a)
309 -> a
310 gunfoldB c f = gmapT (const f) (fromConstr c)
311
312
313 -- | Monadic variation on \"gunfoldB\"
314 gunfoldR :: (Monad m, Data a)
315 => Constr
316 -> (forall a. Data a => m a)
317 -> m a
318 gunfoldR c f = gmapM (const f) $ fromConstr c