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


-- | Functions to transform data structures.
--   
--   This library provides a simple way to transform parts of complex data
--   structures. It is based on Data.Data.
@package data-transform
@version 0.1.0.2


-- | This module provides a simple way to transform parts of complex data
--   structures.
module Data.Transform.Internal

-- | Heterogeneous list structure holding endomorphisms.
data EndoList

-- | Wrapper object holding some endomorphism without exposing its type.
data EndoItem

-- | Heterogeneous list structure holding endomorphisms in a monadic
--   context.
data EndoListM m

-- | Wrapper object holding some endomorphism in a monadic context without
--   exposing its type.
data EndoMItem m

-- | Class of transformations, i.e. objects containing endomorphisms.
class Transformation d

-- | Monadic version of <a>Transformation</a>.
class Monad m => MonadicTransformation d m | d -> m

-- | Wrap a function as an <a>EndoItem</a>.
mkItem :: Data a => (a -> a) -> EndoItem

-- | Wrap a monadic function as an <a>EndoMItem</a>.
mkItemM :: (Monad m, Data a) => (a -> m a) -> EndoMItem m

-- | Transform some data structure by applying one or more endomorphisms to
--   the data structure or any sub-term of it. Sub-terms are transformed
--   before the terms containing them are transformed. If the given
--   endomorphisms contain two or more endomorphisms working on the same
--   type the latter endomorphisms will be applied to the result of the
--   former endomorphisms
--   
--   NOTE: This function attempts to check at runtime if all given
--   endomorphisms can be applied to at least one term in the given
--   argument. If at least one endomorphism can never be applied because of
--   its type, <a>error</a> is called. If you don't want this behavior
--   consider using <a>unsafeTransform</a> instead.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; transform (+1) (1, 4.0, (False, [4, 5, 6]))
--   (2, 4.0, (False, [5, 6, 7]))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; transform [mkItem (+1), mkItem (sqrt :: Double -&gt; Double), mkItem (*2)] (1, 4.0, (False, [4, 5, 6]))
--   (4, 2.0, (False, [10, 12, 14]))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; transform (+1) False
--   *** Exception: Data.DataTraverse.transform: Could not find all needed types when mapping over a value of type Bool. Types of missing terms: [Integer]
--   </pre>
transform :: (Transformation d, Data a) => d -> a -> a

-- | Same as <a>transform</a> but with a monadic function. Calls
--   <a>fail</a> instead of <a>error</a> if a type-error is detected.
transformM :: (MonadicTransformation d m, Data a) => d -> a -> m a

-- | Same as <a>transform</a> but omits any type checking (and hence does
--   not call <a>error</a>).
unsafeTransform :: (Transformation d, Data a) => d -> a -> a

-- | Same as <a>transformM</a> but omits any type checking (and hence does
--   not call <a>fail</a>).
unsafeTransformM :: (MonadicTransformation d m, Data a) => d -> a -> m a

-- | Returns all sub-terms (intermediate and non intermediate) of some type
--   of a value transformed by the supplied function to some <a>Monoid</a>.
--   
--   NOTE: Calls <a>error</a> if no sub-term which the needed type can
--   exist.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; getSubterms (\ x -&gt; if x then [x] else []) (3, 4.0, True, 'c', (False, (True, 5, 6)))
--   [True, True]
--   </pre>
getSubterms :: (Data a, Data b, Monoid m) => (b -> m) -> a -> m

-- | Returns all sub-terms (intermediate and non intermediate) of some type
--   of a value as a list.
--   
--   NOTE: Calls <a>error</a> if no sub-term which the needed type can
--   exist.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; getSubterms' (3, 4.0, True, 'c', (False, (True, 5, 6))) :: [Integer]
--   [3, 5, 6]
--   </pre>
getSubterms' :: (Data a, Data b) => a -> [b]

-- | Returns all sub-terms (intermediate and non intermediate) of some type
--   of a value which fulfill the predicate.
--   
--   NOTE: Calls <a>error</a> if no sub-term which the needed type can
--   exist.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; getSubtermsBy (&lt;6) (3, 4.0, True, 'c', (False, (True, 5, 6)))
--   [3, 5]
--   </pre>
getSubtermsBy :: (Data a, Data b) => (b -> Bool) -> a -> [b]

-- | Returns all sub-terms (intermediate and non intermediate) of some type
--   of a value which could be transformed to some <a>Monoid</a>.
--   
--   NOTE: Calls <a>error</a> if no sub-term which the needed type can
--   exist.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; getSubtermsWith (\ x -&gt; guard (x &lt; 6) &gt;&gt; return [x]) (3, 4.0, True, 'c', (False, (True, 5, 6)))
--   [3, 5]
--   </pre>
getSubtermsWith :: (Data a, Data b, Monoid m) => (b -> Maybe m) -> a -> m
instance GHC.Base.Monad m => GHC.Exts.IsList (Data.Transform.Internal.EndoListM m)
instance GHC.Base.Monad m => Data.Transform.Internal.MonadicTransformation (Data.Transform.Internal.EndoListM m) m
instance GHC.Base.Monad m => Data.Transform.Internal.MonadicTransformation (Data.Transform.Internal.EndoMItem m) m
instance (GHC.Base.Monad m, Data.Data.Data a) => Data.Transform.Internal.MonadicTransformation (a -> m a) m
instance Data.Transform.Internal.MonadicTransformation a m => Data.Transform.Internal.MonadicTransformation [a] m
instance GHC.Exts.IsList Data.Transform.Internal.EndoList
instance Data.Transform.Internal.Transformation Data.Transform.Internal.EndoList
instance Data.Transform.Internal.Transformation Data.Transform.Internal.EndoItem
instance Data.Transform.Internal.Transformation a => Data.Transform.Internal.Transformation [a]
instance Data.Data.Data a => Data.Transform.Internal.Transformation (a -> a)
instance Data.Data.Data a => Data.Transform.Internal.Transformation (Data.Monoid.Endo a)
instance Data.Semigroup.Semigroup (Data.Transform.Internal.EndoListM m)
instance GHC.Base.Monoid (Data.Transform.Internal.EndoListM m)
instance Data.Semigroup.Semigroup Data.Transform.Internal.EndoList
instance GHC.Base.Monoid Data.Transform.Internal.EndoList


-- | This module provides a simple way to transform parts of complex data
--   structures.
module Data.Transform

-- | Wrap a function as an <a>EndoItem</a>.
mkItem :: Data a => (a -> a) -> EndoItem

-- | Wrap a monadic function as an <a>EndoMItem</a>.
mkItemM :: (Monad m, Data a) => (a -> m a) -> EndoMItem m

-- | Transform some data structure by applying one or more endomorphisms to
--   the data structure or any sub-term of it. Sub-terms are transformed
--   before the terms containing them are transformed. If the given
--   endomorphisms contain two or more endomorphisms working on the same
--   type the latter endomorphisms will be applied to the result of the
--   former endomorphisms
--   
--   NOTE: This function attempts to check at runtime if all given
--   endomorphisms can be applied to at least one term in the given
--   argument. If at least one endomorphism can never be applied because of
--   its type, <a>error</a> is called. If you don't want this behavior
--   consider using <a>unsafeTransform</a> instead.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; transform (+1) (1, 4.0, (False, [4, 5, 6]))
--   (2, 4.0, (False, [5, 6, 7]))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; transform [mkItem (+1), mkItem (sqrt :: Double -&gt; Double), mkItem (*2)] (1, 4.0, (False, [4, 5, 6]))
--   (4, 2.0, (False, [10, 12, 14]))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; transform (+1) False
--   *** Exception: Data.DataTraverse.transform: Could not find all needed types when mapping over a value of type Bool. Types of missing terms: [Integer]
--   </pre>
transform :: (Transformation d, Data a) => d -> a -> a

-- | Same as <a>transform</a> but with a monadic function. Calls
--   <a>fail</a> instead of <a>error</a> if a type-error is detected.
transformM :: (MonadicTransformation d m, Data a) => d -> a -> m a

-- | Same as <a>transform</a> but omits any type checking (and hence does
--   not call <a>error</a>).
unsafeTransform :: (Transformation d, Data a) => d -> a -> a

-- | Same as <a>transformM</a> but omits any type checking (and hence does
--   not call <a>fail</a>).
unsafeTransformM :: (MonadicTransformation d m, Data a) => d -> a -> m a

-- | Returns all sub-terms (intermediate and non intermediate) of some type
--   of a value transformed by the supplied function to some <a>Monoid</a>.
--   
--   NOTE: Calls <a>error</a> if no sub-term which the needed type can
--   exist.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; getSubterms (\ x -&gt; if x then [x] else []) (3, 4.0, True, 'c', (False, (True, 5, 6)))
--   [True, True]
--   </pre>
getSubterms :: (Data a, Data b, Monoid m) => (b -> m) -> a -> m

-- | Returns all sub-terms (intermediate and non intermediate) of some type
--   of a value as a list.
--   
--   NOTE: Calls <a>error</a> if no sub-term which the needed type can
--   exist.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; getSubterms' (3, 4.0, True, 'c', (False, (True, 5, 6))) :: [Integer]
--   [3, 5, 6]
--   </pre>
getSubterms' :: (Data a, Data b) => a -> [b]

-- | Returns all sub-terms (intermediate and non intermediate) of some type
--   of a value which fulfill the predicate.
--   
--   NOTE: Calls <a>error</a> if no sub-term which the needed type can
--   exist.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; getSubtermsBy (&lt;6) (3, 4.0, True, 'c', (False, (True, 5, 6)))
--   [3, 5]
--   </pre>
getSubtermsBy :: (Data a, Data b) => (b -> Bool) -> a -> [b]

-- | Returns all sub-terms (intermediate and non intermediate) of some type
--   of a value which could be transformed to some <a>Monoid</a>.
--   
--   NOTE: Calls <a>error</a> if no sub-term which the needed type can
--   exist.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; getSubtermsWith (\ x -&gt; guard (x &lt; 6) &gt;&gt; return [x]) (3, 4.0, True, 'c', (False, (True, 5, 6)))
--   [3, 5]
--   </pre>
getSubtermsWith :: (Data a, Data b, Monoid m) => (b -> Maybe m) -> a -> m