libghc-syb-doc 0.6-1 / usr / share / doc / libghc-syb-doc / html / syb.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Scrap Your Boilerplate
--   
--   This package contains the generics system described in the <i>Scrap
--   Your Boilerplate</i> papers (see
--   <a>http://www.cs.uu.nl/wiki/GenericProgramming/SYB</a>). It defines
--   the <tt>Data</tt> class of types permitting folding and unfolding of
--   constructor applications, instances of this class for primitive types,
--   and a variety of traversals.
@package syb
@version 0.6


-- | "Scrap your boilerplate" --- Generic programming in Haskell. See
--   <a>http://www.cs.uu.nl/wiki/GenericProgramming/SYB</a>. This module
--   provides the <a>Data</a> class with its primitives for generic
--   programming, which is now defined in <tt>Data.Data</tt>. Therefore
--   this module simply re-exports <tt>Data.Data</tt>.
module Data.Generics.Basics


-- | Convenience alias for <a>Data.Generics.Basics</a>.
module Generics.SYB.Basics


-- | "Scrap your boilerplate" --- Generic programming in Haskell See
--   <a>http://www.cs.uu.nl/wiki/GenericProgramming/SYB</a>. The present
--   module contains thirteen <a>Data</a> instances which are considered
--   dubious (either because the types are abstract or just not meant to be
--   traversed). Instances in this module might change or disappear in
--   future releases of this package.
--   
--   (This module does not export anything. It really just defines
--   instances.)
module Data.Generics.Instances
instance Data.Data.Data Data.Typeable.Internal.TypeRep
instance Data.Data.Data Data.Typeable.Internal.TyCon
instance Data.Data.Data Data.Data.DataType
instance Data.Data.Data GHC.IO.Handle.Types.Handle
instance Data.Typeable.Internal.Typeable a => Data.Data.Data (GHC.Stable.StablePtr a)
instance Data.Data.Data GHC.Conc.Sync.ThreadId
instance Data.Typeable.Internal.Typeable a => Data.Data.Data (GHC.Conc.Sync.TVar a)
instance Data.Typeable.Internal.Typeable a => Data.Data.Data (GHC.MVar.MVar a)
instance Data.Typeable.Internal.Typeable a => Data.Data.Data (GHC.Conc.Sync.STM a)
instance (Data.Typeable.Internal.Typeable s, Data.Typeable.Internal.Typeable a) => Data.Data.Data (GHC.ST.ST s a)
instance Data.Typeable.Internal.Typeable a => Data.Data.Data (GHC.IORef.IORef a)
instance Data.Typeable.Internal.Typeable a => Data.Data.Data (GHC.Types.IO a)
instance (Data.Data.Data a, Data.Data.Data b) => Data.Data.Data (a -> b)


-- | Convenience alias for <a>Data.Generics.Instances</a>.
module Generics.SYB.Instances


-- | "Scrap your boilerplate" --- Generic programming in Haskell See
--   <a>http://www.cs.uu.nl/wiki/GenericProgramming/SYB</a>. The present
--   module provides a number of declarations for typical generic function
--   types, corresponding type case, and others.
module Data.Generics.Aliases

-- | Make a generic transformation; start from a type-specific case;
--   preserve the term otherwise
mkT :: (Typeable a, Typeable b) => (b -> b) -> a -> a

-- | Make a generic query; start from a type-specific case; return a
--   constant otherwise
mkQ :: (Typeable a, Typeable b) => r -> (b -> r) -> a -> r

-- | Make a generic monadic transformation; start from a type-specific
--   case; resort to return otherwise
mkM :: (Monad m, Typeable a, Typeable b) => (b -> m b) -> a -> m a

-- | Make a generic monadic transformation for MonadPlus; use "const mzero"
--   (i.e., failure) instead of return as default.
mkMp :: (MonadPlus m, Typeable a, Typeable b) => (b -> m b) -> a -> m a

-- | Make a generic builder; start from a type-specific ase; resort to no
--   build (i.e., mzero) otherwise
mkR :: (MonadPlus m, Typeable a, Typeable b) => m b -> m a

-- | Flexible type extension
ext0 :: (Typeable a, Typeable b) => c a -> c b -> c a

-- | Extend a generic transformation by a type-specific case
extT :: (Typeable a, Typeable b) => (a -> a) -> (b -> b) -> a -> a

-- | Extend a generic query by a type-specific case
extQ :: (Typeable a, Typeable b) => (a -> q) -> (b -> q) -> a -> q

-- | Extend a generic monadic transformation by a type-specific case
extM :: (Monad m, Typeable a, Typeable b) => (a -> m a) -> (b -> m b) -> a -> m a

-- | Extend a generic MonadPlus transformation by a type-specific case
extMp :: (MonadPlus m, Typeable a, Typeable b) => (a -> m a) -> (b -> m b) -> a -> m a

-- | Extend a generic builder
extB :: (Typeable a, Typeable b) => a -> b -> a

-- | Extend a generic reader
extR :: (Monad m, Typeable a, Typeable b) => m a -> m b -> m a

-- | Generic transformations, i.e., take an "a" and return an "a"
type GenericT = forall a. Data a => a -> a

-- | Generic queries of type "r", i.e., take any "a" and return an "r"
type GenericQ r = forall a. Data a => a -> r

-- | Generic monadic transformations, i.e., take an "a" and compute an "a"
type GenericM m = forall a. Data a => a -> m a

-- | Generic builders i.e., produce an "a".
type GenericB = forall a. Data a => a

-- | Generic readers, say monadic builders, i.e., produce an "a" with the
--   help of a monad "m".
type GenericR m = forall a. Data a => m a

-- | The general scheme underlying generic functions assumed by gfoldl;
--   there are isomorphisms such as GenericT = Generic T.
type Generic c = forall a. Data a => a -> c a

-- | Wrapped generic functions; recall: [Generic c] would be legal but
--   [Generic' c] not.
data Generic' c
Generic' :: Generic c -> Generic' c
[unGeneric'] :: Generic' c -> Generic c

-- | Other first-class polymorphic wrappers
newtype GenericT'
GT :: (forall a. Data a => a -> a) -> GenericT'
[unGT] :: GenericT' -> forall a. Data a => a -> a
newtype GenericQ' r
GQ :: GenericQ r -> GenericQ' r
[unGQ] :: GenericQ' r -> GenericQ r
newtype GenericM' m
GM :: (forall a. Data a => a -> m a) -> GenericM' m
[unGM] :: GenericM' m -> forall a. Data a => a -> m a

-- | Left-biased choice on maybes
orElse :: Maybe a -> Maybe a -> Maybe a

-- | Recover from the failure of monadic transformation by identity
recoverMp :: MonadPlus m => GenericM m -> GenericM m

-- | Recover from the failure of monadic query by a constant
recoverQ :: MonadPlus m => r -> GenericQ (m r) -> GenericQ (m r)

-- | Choice for monadic transformations
choiceMp :: MonadPlus m => GenericM m -> GenericM m -> GenericM m

-- | Choice for monadic queries
choiceQ :: MonadPlus m => GenericQ (m r) -> GenericQ (m r) -> GenericQ (m r)

-- | Flexible type extension
ext1 :: (Data a, Typeable t) => c a -> (forall d. Data d => c (t d)) -> c a

-- | Type extension of transformations for unary type constructors
ext1T :: (Data d, Typeable t) => (forall e. Data e => e -> e) -> (forall f. Data f => t f -> t f) -> d -> d

-- | Type extension of monadic transformations for type constructors
ext1M :: (Monad m, Data d, Typeable t) => (forall e. Data e => e -> m e) -> (forall f. Data f => t f -> m (t f)) -> d -> m d

-- | Type extension of queries for type constructors
ext1Q :: (Data d, Typeable t) => (d -> q) -> (forall e. Data e => t e -> q) -> d -> q

-- | Type extension of readers for type constructors
ext1R :: (Monad m, Data d, Typeable t) => m d -> (forall e. Data e => m (t e)) -> m d

-- | Type extension of builders for type constructors
ext1B :: (Data a, Typeable t) => a -> (forall b. Data b => (t b)) -> a

-- | Type extension of transformations for unary type constructors
ext2T :: (Data d, Typeable t) => (forall e. Data e => e -> e) -> (forall d1 d2. (Data d1, Data d2) => t d1 d2 -> t d1 d2) -> d -> d

-- | Type extension of monadic transformations for type constructors
ext2M :: (Monad m, Data d, Typeable t) => (forall e. Data e => e -> m e) -> (forall d1 d2. (Data d1, Data d2) => t d1 d2 -> m (t d1 d2)) -> d -> m d

-- | Type extension of queries for type constructors
ext2Q :: (Data d, Typeable t) => (d -> q) -> (forall d1 d2. (Data d1, Data d2) => t d1 d2 -> q) -> d -> q

-- | Type extension of readers for type constructors
ext2R :: (Monad m, Data d, Typeable t) => m d -> (forall d1 d2. (Data d1, Data d2) => m (t d1 d2)) -> m d

-- | Type extension of builders for type constructors
ext2B :: (Data a, Typeable t) => a -> (forall d1 d2. (Data d1, Data d2) => (t d1 d2)) -> a


-- | "Scrap your boilerplate" --- Generic programming in Haskell See
--   <a>http://www.cs.uu.nl/wiki/GenericProgramming/SYB</a>. The present
--   module provides frequently used generic traversal schemes.
module Data.Generics.Schemes

-- | Apply a transformation everywhere in bottom-up manner
everywhere :: (forall a. Data a => a -> a) -> (forall a. Data a => a -> a)

-- | Apply a transformation everywhere in top-down manner
everywhere' :: (forall a. Data a => a -> a) -> (forall a. Data a => a -> a)

-- | Variation on everywhere with an extra stop condition
everywhereBut :: GenericQ Bool -> GenericT -> GenericT

-- | Monadic variation on everywhere
everywhereM :: Monad m => GenericM m -> GenericM m

-- | Apply a monadic transformation at least somewhere
somewhere :: MonadPlus m => GenericM m -> GenericM m

-- | Summarise all nodes in top-down, left-to-right order
everything :: (r -> r -> r) -> GenericQ r -> GenericQ r

-- | Variation of "everything" with an added stop condition
everythingBut :: (r -> r -> r) -> GenericQ (r, Bool) -> GenericQ r

-- | Summarise all nodes in top-down, left-to-right order, carrying some
--   state down the tree during the computation, but not left-to-right to
--   siblings.
everythingWithContext :: s -> (r -> r -> r) -> GenericQ (s -> (r, s)) -> GenericQ r

-- | Get a list of all entities that meet a predicate
listify :: Typeable r => (r -> Bool) -> GenericQ [r]

-- | Look up a subterm by means of a maybe-typed filter
something :: GenericQ (Maybe u) -> GenericQ (Maybe u)

-- | Bottom-up synthesis of a data structure; 1st argument z is the initial
--   element for the synthesis; 2nd argument o is for reduction of results
--   from subterms; 3rd argument f updates the synthesised data according
--   to the given term
synthesize :: s -> (t -> s -> s) -> GenericQ (s -> t) -> GenericQ t

-- | Compute size of an arbitrary data structure
gsize :: Data a => a -> Int

-- | Count the number of immediate subterms of the given term
glength :: GenericQ Int

-- | Determine depth of the given term
gdepth :: GenericQ Int

-- | Determine the number of all suitable nodes in a given term
gcount :: GenericQ Bool -> GenericQ Int

-- | Determine the number of all nodes in a given term
gnodecount :: GenericQ Int

-- | Determine the number of nodes of a given type in a given term
gtypecount :: Typeable a => a -> GenericQ Int

-- | Find (unambiguously) an immediate subterm of a given type
gfindtype :: (Data x, Typeable y) => x -> Maybe y


-- | Convenience alias for <a>Data.Generics.Schemes</a>.
module Generics.SYB.Schemes


-- | "Scrap your boilerplate" --- Generic programming in Haskell See
--   <a>http://www.cs.uu.nl/wiki/GenericProgramming/SYB</a>. The present
--   module provides generic operations for text serialisation of terms.
module Data.Generics.Text

-- | Generic show: an alternative to "deriving Show"
gshow :: Data a => a -> String

-- | Generic shows
gshows :: Data a => a -> ShowS

-- | Generic read: an alternative to "deriving Read"
gread :: Data a => ReadS a


-- | Convenience alias for <a>Data.Generics.Text</a>.
module Generics.SYB.Text


-- | "Scrap your boilerplate" --- Generic programming in Haskell See
--   <a>http://www.cs.uu.nl/wiki/GenericProgramming/SYB</a>. The present
--   module provides support for multi-parameter traversal, which is also
--   demonstrated with generic operations like equality.
module Data.Generics.Twins

-- | gfoldl with accumulation
gfoldlAccum :: Data d => (forall e r. Data e => a -> c (e -> r) -> e -> (a, c r)) -> (forall g. a -> g -> (a, c g)) -> a -> d -> (a, c d)

-- | gmapT with accumulation
gmapAccumT :: Data d => (forall e. Data e => a -> e -> (a, e)) -> a -> d -> (a, d)

-- | gmapM with accumulation
gmapAccumM :: (Data d, Monad m) => (forall e. Data e => a -> e -> (a, m e)) -> a -> d -> (a, m d)

-- | gmapQl with accumulation
gmapAccumQl :: Data d => (r -> r' -> r) -> r -> (forall e. Data e => a -> e -> (a, r')) -> a -> d -> (a, r)

-- | gmapQr with accumulation
gmapAccumQr :: Data d => (r' -> r -> r) -> r -> (forall e. Data e => a -> e -> (a, r')) -> a -> d -> (a, r)

-- | gmapQ with accumulation
gmapAccumQ :: Data d => (forall e. Data e => a -> e -> (a, q)) -> a -> d -> (a, [q])

-- | Applicative version
gmapAccumA :: (Data d, Applicative a) => (forall e. Data e => b -> e -> (b, a e)) -> b -> d -> (b, a d)

-- | Twin map for transformation
gzipWithT :: GenericQ (GenericT) -> GenericQ (GenericT)

-- | Twin map for monadic transformation
gzipWithM :: Monad m => GenericQ (GenericM m) -> GenericQ (GenericM m)

-- | Twin map for queries
gzipWithQ :: GenericQ (GenericQ r) -> GenericQ (GenericQ [r])

-- | Generic equality: an alternative to "deriving Eq"
geq :: Data a => a -> a -> Bool

-- | Generic zip controlled by a function with type-specific branches
gzip :: GenericQ (GenericM Maybe) -> GenericQ (GenericM Maybe)

-- | Generic comparison: an alternative to "deriving Ord"
gcompare :: Data a => a -> a -> Ordering


-- | Convenience alias for <a>Data.Generics.Twins</a>.
module Generics.SYB.Twins


-- | This module provides generic builder functions. These functions
--   construct values of a given type.
module Data.Generics.Builders

-- | Construct the empty value for a datatype. For algebraic datatypes, the
--   leftmost constructor is chosen.
empty :: Data a => a

-- | Return a list of values of a datatype. Each value is one of the
--   possible constructors of the datatype, populated with <a>empty</a>
--   values.
constrs :: Data a => [a]


-- | Convenience alias for <a>Data.Generics.Builders</a>.
module Generics.SYB.Builders


-- | Convenience alias for <a>Data.Generics.Aliases</a>.
module Generics.SYB.Aliases


-- | "Scrap your boilerplate" --- Generic programming in Haskell See
--   <a>http://www.cs.uu.nl/wiki/GenericProgramming/SYB</a>. To scrap your
--   boilerplate it is sufficient to import the present module, which
--   simply re-exports all themes of the Data.Generics library.
module Data.Generics


-- | Convenience alias for <a>Data.Generics</a>.
module Generics.SYB