1 -----------------------------------------------------------------------------
3 -- Module : Data.Generics
4 -- Copyright : (c) The University of Glasgow, CWI 2001--2003
5 -- License : BSD-style (see the file libraries/base/LICENSE)
7 -- Maintainer : libraries@haskell.org, ralf@cwi.nl
8 -- Stability : experimental
9 -- Portability : non-portable
11 -- Generic programming in Haskell;
12 -- see <http://www.cs.vu.nl/boilerplate>.
14 -----------------------------------------------------------------------------
16 module Data.Generics (
18 -- The Typeable class and the type-safe cast operation;
19 -- re-exported for convenience
22 -- * Prime types of generic functions
23 GenericT, GenericQ, GenericM,
25 -- * Combinators to \"make\" generic functions
26 mkT, mkQ, mkM, extT, extQ, extM, sameType,
28 -- * The Data class for folding and unfolding constructor applications
38 -- * The Constr datatype for describing datatype constructors
41 -- * Frequently used generic traversal schemes
50 -- * Generic operations such as show, equality, read
61 -- Data types for the sum-of-products type encoding;
62 -- included for backwards compatibility; maybe obsolete
63 (:*:)(..), (:+:)(..), Unit(..)
68 ------------------------------------------------------------------------------
70 import Prelude -- So that 'make depend' works
72 #ifdef __GLASGOW_HASKELL__
74 import GHC.Base ( (:*:)(..), (:+:)(..), Unit(..) )
83 ------------------------------------------------------------------------------
85 -- Prime types of generic functions
87 ------------------------------------------------------------------------------
89 -- | Generic transformations,
90 -- i.e., take an \"a\" and return an \"a\"
92 type GenericT = forall a. Data a => a -> a
95 -- | Generic queries of type "r",
96 -- i.e., take any \"a\" and return an \"r\"
98 type GenericQ r = forall a. Data a => a -> r
101 -- | Generic monadic transformations,
102 -- i.e., take an \"a\" and compute an \"a\"
104 type GenericM m = forall a. Data a => a -> m a
108 ------------------------------------------------------------------------------
110 -- Combinators to "make" generic functions
111 -- We use type-safe cast in a number of ways to make generic functions.
113 ------------------------------------------------------------------------------
115 -- | Make a generic transformation;
116 -- start from a type-specific case;
117 -- preserve the term otherwise
119 mkT :: (Typeable a, Typeable b) => (b -> b) -> a -> a
120 mkT f = case cast f of
125 -- | Make a generic query;
126 -- start from a type-specific case;
127 -- return a constant otherwise
129 mkQ :: (Typeable a, Typeable b) => r -> (b -> r) -> a -> r
130 (r `mkQ` br) a = case cast a of
135 -- | Make a generic monadic transformation;
136 -- start from a type-specific case;
137 -- resort to return otherwise
139 mkM :: (Typeable a, Typeable b, Typeable (m a), Typeable (m b), Monad m)
140 => (b -> m b) -> a -> m a
141 mkM f = case cast f of
146 -- | Extend a generic transformation by a type-specific case
147 extT :: (Typeable a, Typeable b) => (a -> a) -> (b -> b) -> a -> a
148 extT f g = case cast g of
153 -- | Extend a generic query by a type-specific case
154 extQ :: (Typeable a, Typeable b) => (a -> q) -> (b -> q) -> a -> q
155 extQ f g a = case cast a of
160 -- | Extend a generic monadic transformation by a type-specific case
161 extM :: (Typeable a, Typeable b, Typeable (m a), Typeable (m b), Monad m)
162 => (a -> m a) -> (b -> m b) -> a -> m a
163 extM f g = case cast g of
168 -- | Test for two objects to agree on the type
169 sameType :: (Typeable a, Typeable b) => a -> b -> Bool
170 sameType (_::a) = maybe False (\(_::a) -> True) . cast
174 ------------------------------------------------------------------------------
178 ------------------------------------------------------------------------------
180 class Typeable a => Data a where
182 -- | A generic transformation that maps over the immediate subterms
183 gmapT :: (forall b. Data b => b -> b) -> a -> a
185 -- | A generic query that processes the immediate subterms and returns a list
186 gmapQ :: (forall a. Data a => a -> u) -> a -> [u]
188 -- | A monadic variation on generic transformation
189 gmapM :: Monad m => (forall a. Data a => a -> m a) -> a -> m a
191 -- | Left-associative fold operation for constructor applications
192 gfoldl :: (forall a b. Data a => c (a -> b) -> a -> c b)
193 -> (forall g. g -> c g)
196 -- | Obtain the constructor from a given term
199 -- | List all constructors for a given type
200 consOf :: a -> [Constr]
202 -- | Unfold operation to build terms from constructors and others
203 gunfold :: (forall a b. Data a => c (a -> b) -> c b)
204 -> (forall g. g -> c g)
208 -- Default definition for gfoldl
209 -- which copes immediately with basic datatypes
216 The combinators gmapT, gmapQ, gmapM can all be defined in terms of
217 gfoldl. We provide corresponding default definitions leaving open the
218 opportunity to provide datatype-specific definitions if needed.
220 (Also, the inclusion of the gmap combinators as members of class Data
221 allows the programmer or the compiler to derive specialised, and maybe
222 more efficient code per datatype. Note: gfoldl is more higher-order
223 than the gmap combinators. This is subject to ongoing benchmarking
226 Conceptually, the definition of the gmap combinators in terms of the
227 primitive gfoldl requires the identification of the gfoldl function
228 arguments. Technically, we also need to identify the type constructor
229 c used all over the type of gfoldl. We give the default definitions in
230 the order of increasing headache.
234 -- Use immediately the monad datatype constructor
235 -- to instantiate the type constructor c in the type of gfoldl,
236 -- so injection and projection is done by return and >>=.
238 gmapM f = gfoldl k return
244 -- Use an identity datatype constructor ID (see below)
245 -- to instantiate the type constructor c in the type of gfoldl,
246 -- and perform injections ID and projections unID accordingly.
248 gmapT f x = unID (gfoldl k ID x)
250 k (ID c) x = ID (c (f x))
252 -- Use a phantom + function datatype constructor Q (see below),
253 -- to instantiate the type constructor c in the type of gfoldl,
254 -- and perform injections Q and projections unQ accordingly.
256 gmapQ f x = unQ (gfoldl k (const (Q id)) x) []
258 k (Q c) x = Q (\rs -> c (f x : rs))
261 -- | The identity type constructor needed for the definition of gmapT
262 newtype ID x = ID { unID :: x }
265 -- | A phantom datatype constructor used in definition of gmapQ;
266 -- the function-typed component is needed to mediate between
267 -- left-associative constructor application vs. right-associative lists.
269 newtype Q r a = Q { unQ :: [r] -> [r] }
273 ------------------------------------------------------------------------------
275 -- The Constr datatype for describing datatype constructors
276 -- To be extended by fixity, associativity, and maybe others.
278 ------------------------------------------------------------------------------
280 -- | Description of datatype constructors
281 data Constr = Constr { conString :: String }
286 It is interesting to observe that we can determine the arity of a
287 constructor without further meta-information. To this end, we use
288 gunfold to construct a term from a given constructor while leaving the
289 subterms undefined. Here we instantiate the type constructor c of the
290 gunfold type by the identity type constructor ID. In a subsequent step
291 we determine the number of subterms by folding as captured in the
292 generic operation glength elsewhere in this module. Note that we need
293 an extra argument to specify the intended type of the constructor.
297 garity :: Data a => (a -> ()) -> Constr -> Int
298 garity (_::a->()) = glength
299 . (unID :: ID a -> a)
302 bottom = (\f -> ID (f undefined)) . unID
306 ------------------------------------------------------------------------------
308 -- Frequently used generic traversal schemes
310 ------------------------------------------------------------------------------
312 -- | Apply a transformation everywhere in bottom-up manner
313 everywhere :: (forall a. Data a => a -> a)
314 -> (forall a. Data a => a -> a)
316 -- use gmapT to recurse into immediate subterms;
317 -- recall: gmapT preserves the outermost constructor;
318 -- post-process recursively transformed result via f
320 everywhere f = f . gmapT (everywhere f)
323 -- | Apply a transformation everywhere in top-down manner
324 everywhere' :: (forall a. Data a => a -> a)
325 -> (forall a. Data a => a -> a)
327 -- Arguments of (.) are flipped compared to everywhere
328 everywhere' f = gmapT (everywhere' f) . f
331 -- | Variation on everywhere with an extra stop condition
332 everywhereBut :: GenericQ Bool -> GenericT -> GenericT
334 -- Guarded to let traversal cease if predicate q holds for x
337 | otherwise = f (gmapT (everywhereBut q f) x)
340 -- | Monadic variation on everywhere
341 everywhereM :: Monad m => GenericM m -> GenericM m
343 -- Bottom-up order is also reflected in order of do-actions
344 everywhereM f x = do x' <- gmapM (everywhereM f) x
348 -- | Summarise all nodes in top-down, left-to-right order
349 everything :: (r -> r -> r) -> GenericQ r -> GenericQ r
351 -- Apply f to x to summarise top-level node;
352 -- use gmapQ to recurse into immediate subterms;
353 -- use ordinary foldl to reduce list of intermediate results
356 = foldl k (f x) (gmapQ (everything k f) x)
359 -- | Look up a subterm by means of a maybe-typed filter
360 something :: GenericQ (Maybe u) -> GenericQ (Maybe u)
362 -- "something" can be defined in terms of "everything"
363 -- when a suitable "choice" operator is used for reduction
365 something = everything orElse
368 -- Left-biased choice on maybes (non-strict in right argument)
369 orElse :: Maybe a -> Maybe a -> Maybe a
370 x `orElse` y = maybe y Just x
373 -- Another definition of orElse
374 -- where the folding over maybies as defined by maybe is inlined
375 -- to ease readability
377 x `orElse'` y = case x of
384 -- | Bottom-up synthesis of a data structure;
385 -- 1st argument z is the initial element for the synthesis;
386 -- 2nd argument o is for reduction of results from subterms;
387 -- 3rd argument f updates the sythesised data according to the given term
389 synthesize :: s -> (s -> s -> s) -> GenericQ (s -> s) -> GenericQ s
390 synthesize z o f x = f x (foldr o z (gmapQ (synthesize z o f) x))
394 -----------------------------------------------------------------------------
396 -- "Twin" variations on gmapT, gmapQ. gmapM,
397 -- i.e., these combinators take two terms at the same time.
398 -- They are needed for multi-parameter traversal as generic equality.
399 -- They are not exported.
401 -----------------------------------------------------------------------------
405 We need type constructors for twin traversal as we needed type
406 constructor for the ordinary gmap combinators. These type constructors
407 again serve for the instantiation of the type constructor c used in
408 the definition of gfoldl. The type constructors for twin traversal are
409 elaborations of the type constructors ID, Q and monads that were used
410 for the ordinary gmap combinators. More precisely, we use a pairing
411 technique to always attach an additional component to the results of
412 folding. This additional component carries the list of generic
413 functions to be used for the intermediate subterms encountered during
418 newtype TT r a = TT { unTT :: (a,[GenericT']) }
419 newtype TQ r a = TQ { unTQ :: ([r]->[r],[GenericQ' r]) }
420 newtype TM m a = TM { unTM :: (m a,[GenericM' m]) }
423 -- First-class polymorphic versions of GenericT/GenericQ/GenericM;
424 -- they are referenced in TQ amd TM above
426 data GenericT' = T' { unT' :: forall a. Data a => a -> a }
427 data GenericQ' u = Q' { unQ' :: forall a. Data a => a -> u }
428 data Monad m => GenericM' m = M' { unM' :: forall a. Data a => a -> m a }
433 A twin variation on gmapT, where the pattern "GenericQ GenericT"
434 expresses that the argument terms x and y are processed rather
435 independently. So firstly, x is "queried" with a generic
436 transformation as intermediate result, and secondly, this generic
437 transformation is applied to y.
441 tmapT :: GenericQ GenericT -> GenericQ GenericT
442 tmapT g x y = fst (unTT (gfoldl k z y))
444 k (TT (f,l)) x = TT (f (unT' (head l) x),tail l)
445 z f = TT (f,gmapQ (\x -> T' (g x)) x)
449 -- A twin variation on gmapQ
452 (forall a b. (Data a, Data b) => a -> b -> r)
453 -> (forall a b. (Data a, Data b) => a -> b -> [r])
455 tmapQ g x y = fst (unTQ (gfoldl k z y)) []
457 k (TQ (c,l)) x = TQ (\rs -> c (unQ' (head l) x:rs), tail l)
458 z _ = TQ (id,gmapQ (\x -> Q' (g x)) x)
461 -- A twin variation on gmapM
463 tmapM :: forall m. Monad m
464 => (forall a b. (Data a, Data b) => a -> b -> m b)
465 -> (forall a b. (Data a, Data b) => a -> b -> m b)
466 tmapM g x y = fst (unTM (gfoldl k z y))
468 k (TM (f,l)) x = TM (f >>= \f' -> unM' (head l) x >>= return . f',tail l)
469 z f = TM (return f,gmapQ (\x -> M' (g x)) x)
473 ------------------------------------------------------------------------------
475 -- Generic operations such as show, equality, read
477 ------------------------------------------------------------------------------
479 -- | Count the number of immediate subterms of the given term
480 glength :: GenericQ Int
481 glength = length . gmapQ (const ())
484 -- | Determine the number of all nodes in a given term
485 gnodecount :: GenericQ Int
486 gnodecount = everything (+) (const 1)
489 -- | Determine the number of nodes of a given type in a given term
490 gtypecount :: Typeable a => (a -> ()) -> GenericQ Int
491 gtypecount f = everything (+) (0 `mkQ` (const 1 . f))
494 -- | Generic show: an alternative to "deriving Show"
495 gshow :: Data a => a -> String
497 -- This is a prefix-show using surrounding "(" and ")",
498 -- where we recurse into subterms with gmapQ.
501 ++ conString (conOf t)
502 ++ concat (gmapQ ((++) " " . gshow) t)
506 -- | Generic equality: an alternative to "deriving Eq"
507 geq :: forall a. Data a => a -> a -> Bool
511 We establish the equality of the two top-level datatype constructors.
512 We use a twin gmap combinator, namely tgmapQ, to compare the two lists
513 of immediate subterms.
515 (Note for the experts: the type of the worker geq' is rather general
516 but precision is recovered via the restrictive type of the top-level
517 operation geq. The imprecision of geq' is caused by the type system's
518 unability to express the type equivalence for the corresponding
519 couples of immediate subterms from the two given input terms.)
525 geq' :: forall a b. (Data a, Data b) => a -> b -> Bool
526 geq' x y = and ( (conString (conOf x) == conString (conOf y))
531 -- | Generic zip controlled by a function with type-specific branches
532 gzip :: (forall a b. (Data a, Data b) => a -> b -> Maybe b)
533 -> (forall a b. (Data a, Data b) => a -> b -> Maybe b)
535 -- See testsuite/.../Generics/gzip.hs for an illustration
539 if conString (conOf x) == conString (conOf y)
540 then tmapM (gzip f) x y
544 -- | The type constructor for gunfold a la ReadS from the Haskell 98 Prelude
545 newtype GRead i a = GRead (i -> Maybe (a, i))
546 unGRead (GRead x) = x
549 -- | Generic read: an alternative to "deriving Read"
550 gread :: Data a => String -> Maybe (a, String)
554 This is a read operation which insists on prefix notation.
555 (The Haskell 98 read is closer to conrete syntax.)
556 We use gunfold to "parse" the input.
561 = do s' <- return $ dropWhile ((==) ' ') s
562 guard (not (s' == ""))
563 guard (head s' == '(')
564 (c,s'') <- prefixConstr (dropWhile ((==) ' ') (tail s'))
565 (a,s''') <- unGRead (gunfold f z c) s''
566 guard (not (s''' == ""))
567 guard (head s''' == ')')
571 -- Argument f for unfolding
572 f :: Data a => GRead String (a -> b) -> GRead String b
573 f x = GRead (\s -> do (r,s') <- unGRead x s
577 -- Argument z for unfolding
578 z :: forall g. g -> GRead String g
579 z g = GRead (\s -> return (g,s))
581 -- Get Constr at front of string
582 prefixConstr :: String -> Maybe (Constr, String)
584 -- Assume an infix operators in parantheses
586 = case break ((==) ')') s of
587 (s'@(_:_),(')':s'')) -> Just (Constr ("(" ++ s' ++ ")"), s'')
590 -- Special treatment of multiple token constructors
591 prefixConstr ('[':']':s) = Just (Constr "[]",s)
593 -- Try lex for ordinary constructor and basic datatypes
596 [(s'@(_:_),s'')] -> Just (Constr s',s'')
601 ------------------------------------------------------------------------------
603 -- Instances of the Data class
605 ------------------------------------------------------------------------------
607 -- Basic datatype Int; folding and unfolding is trivial
608 instance Data Int where
609 conOf x = Constr (show x)
611 gunfold f z c = z (read (conString c))
613 -- Another basic datatype instance
614 instance Data Integer where
615 conOf x = Constr (show x)
617 gunfold f z c = z (read (conString c))
619 -- Another basic datatype instance
620 instance Data Float where
621 conOf x = Constr (show x)
623 gunfold f z c = z (read (conString c))
625 -- Another basic datatype instance
626 instance Data Char where
627 conOf x = Constr (show x)
629 gunfold f z c = z (read (conString c))
634 subject to inclusion of a missing Typeable instance
636 -- Another basic datatype instance
637 instance Data Rational where
638 conOf x = Constr (show x)
640 gunfold f z c = z (read (conString c))
644 -- Bool as a kind of enumeration type
645 instance Data Bool where
646 conOf False = Constr "False"
647 conOf True = Constr "True"
648 consOf _ = [Constr "False",Constr "True"]
649 gunfold f z (Constr "False") = z False
650 gunfold f z (Constr "True") = z True
654 We should better not fold over characters in a string for efficiency.
655 However, the following instance would clearly overlap with the
656 instance for polymorphic lists. Given the current scheme of allowing
657 overlapping instances, this would imply that ANY module that imports
658 Data.Generics would need to explicitly and generally allow overlapping
659 instances. This is prohibitive and calls for a more constrained model
660 of allowing overlapping instances.
662 -- instance Data String where
663 conOf x = Constr (show x)
665 gunfold f z c = z (read (conString c))
669 -- Cons-lists are terms with two immediate subterms. Hence, the gmap
670 -- combinators do NOT coincide with the list fold/map combinators.
672 instance Data a => Data [a] where
674 gmapT f (x:xs) = (f x:f xs)
676 gmapQ f (x:xs) = [f x,f xs]
677 gmapM f [] = return []
678 gmapM f (x:xs) = f x >>= \x' -> f xs >>= \xs' -> return (x':xs')
680 gfoldl f z (x:xs) = z (:) `f` x `f` xs
681 conOf [] = Constr "[]"
682 conOf (_:_) = Constr "(:)"
683 consOf _ = [Constr "[]",Constr "(:)"]
684 gunfold f z (Constr "[]") = z []
685 gunfold f z (Constr "(:)") = f (f (z (:)))
687 -- Yet enother polymorphic datatype constructor
688 instance Data a => Data (Maybe a) where
689 gfoldl f z Nothing = z Nothing
690 gfoldl f z (Just x) = z Just `f` x
691 conOf Nothing = Constr "Nothing"
692 conOf (Just _) = Constr "Just"
693 consOf _ = [Constr "Nothing", Constr "Just"]
694 gunfold f z c | conString c == "Nothing" = z Nothing
695 gunfold f z c | conString c == "Just" = f (z Just)
697 -- Yet enother polymorphic datatype constructor
698 instance (Data a, Data b) => Data (a,b) where
699 gfoldl f z (a,b) = z (,) `f` a `f` b
700 conOf _ = Constr "(,)"
701 consOf _ = [Constr "(,)"]
702 gunfold f z c | conString c == "(,)" = f (f (z (,)))
704 -- Functions are treated as "non-compound" data regarding folding while
705 -- unfolding is out of reach, maybe not anymore with Template Haskell.
707 instance (Typeable a, Typeable b) => Data (a -> b) where
708 conOf _ = Constr "->"
709 consOf _ = [Constr "->"]
710 gunfold _ _ _ = undefined