Safe Haskell | Safe |
---|---|

Language | Haskell2010 |

## Synopsis

- module Data.Data
- gtraverse :: (Applicative f, Data a) => (forall d. Data d => d -> f d) -> a -> f a
- class Plated a
- plate :: Plated a => Traversal' a a
- template :: (Data s, Typeable a) => Traversal' s a
- tinplate :: (Data s, Typeable a) => Traversal' s a
- uniplate :: Data a => Traversal' a a
- biplate :: (Data s, Typeable a) => Traversal' s a
- children :: Plated a => a -> [a]
- rewrite :: Plated a => (a -> Maybe a) -> a -> a
- rewriteOf :: ASetter a b a b -> (b -> Maybe a) -> a -> b
- rewriteOn :: Plated a => ASetter s t a a -> (a -> Maybe a) -> s -> t
- rewriteOnOf :: ASetter s t a b -> ASetter a b a b -> (b -> Maybe a) -> s -> t
- rewriteM :: (Monad m, Plated a) => (a -> m (Maybe a)) -> a -> m a
- rewriteMOf :: Monad m => LensLike (WrappedMonad m) a b a b -> (b -> m (Maybe a)) -> a -> m b
- rewriteMOn :: (Monad m, Plated a) => LensLike (WrappedMonad m) s t a a -> (a -> m (Maybe a)) -> s -> m t
- rewriteMOnOf :: Monad m => LensLike (WrappedMonad m) s t a b -> LensLike (WrappedMonad m) a b a b -> (b -> m (Maybe a)) -> s -> m t
- universe :: Plated a => a -> [a]
- universeOf :: Getting [a] a a -> a -> [a]
- universeOn :: Plated a => Getting [a] s a -> s -> [a]
- universeOnOf :: Getting [a] s a -> Getting [a] a a -> s -> [a]
- cosmos :: Plated a => Fold a a
- cosmosOf :: (Applicative f, Contravariant f) => LensLike' f a a -> LensLike' f a a
- cosmosOn :: (Applicative f, Contravariant f, Plated a) => LensLike' f s a -> LensLike' f s a
- cosmosOnOf :: (Applicative f, Contravariant f) => LensLike' f s a -> LensLike' f a a -> LensLike' f s a
- transform :: Plated a => (a -> a) -> a -> a
- transformOf :: ASetter a b a b -> (b -> b) -> a -> b
- transformOnOf :: ASetter s t a b -> ASetter a b a b -> (b -> b) -> s -> t
- transformM :: (Monad m, Plated a) => (a -> m a) -> a -> m a
- transformMOf :: Monad m => LensLike (WrappedMonad m) a b a b -> (b -> m b) -> a -> m b
- transformMOn :: (Monad m, Plated a) => LensLike (WrappedMonad m) s t a a -> (a -> m a) -> s -> m t
- transformMOnOf :: Monad m => LensLike (WrappedMonad m) s t a b -> LensLike (WrappedMonad m) a b a b -> (b -> m b) -> s -> m t
- contexts :: Plated a => a -> [Context a a a]
- contextsOf :: ATraversal' a a -> a -> [Context a a a]
- contextsOn :: Plated a => ATraversal s t a a -> s -> [Context a a t]
- contextsOnOf :: ATraversal s t a a -> ATraversal' a a -> s -> [Context a a t]
- holes :: Plated a => a -> [Pretext ((->) :: * -> * -> *) a a a]
- holesOn :: Conjoined p => Over p (Bazaar p a a) s t a a -> s -> [Pretext p a a t]
- holesOnOf :: Conjoined p => LensLike (Bazaar p r r) s t a b -> Over p (Bazaar p r r) a b r r -> s -> [Pretext p r r t]
- para :: Plated a => (a -> [r] -> r) -> a -> r
- paraOf :: Getting (Endo [a]) a a -> (a -> [r] -> r) -> a -> r
- deep :: (Conjoined p, Applicative f, Plated s) => Traversing p f s s a b -> Over p f s s a b
- composOpFold :: Plated a => b -> (b -> b -> b) -> (a -> b) -> a -> b
- parts :: Plated a => Lens' a [a]

# Documentation

module Data.Data

gtraverse :: (Applicative f, Data a) => (forall d. Data d => d -> f d) -> a -> f a #

A `Plated`

type is one where we know how to extract its immediate self-similar children.

*Example 1*:

```
import Control.Applicative
import Control.Lens
import Control.Lens.Plated
import Data.Data
import Data.Data.Lens (
````uniplate`

)

data Expr = Val`Int`

| Neg Expr | Add Expr Expr deriving (`Eq`

,`Ord`

,`Show`

,`Read`

,`Data`

,`Typeable`

)

instance`Plated`

Expr where`plate`

f (Neg e) = Neg`<$>`

f e`plate`

f (Add a b) = Add`<$>`

f a`<*>`

f b`plate`

_ a =`pure`

a

*or*

instance`Plated`

Expr where`plate`

=`uniplate`

*Example 2*:

```
import Control.Applicative
import Control.Lens
import Control.Lens.Plated
import Data.Data
import Data.Data.Lens (
````uniplate`

)

data Tree a = Bin (Tree a) (Tree a) | Tip a deriving (`Eq`

,`Ord`

,`Show`

,`Read`

,`Data`

,`Typeable`

)

instance`Plated`

(Tree a) where`plate`

f (Bin l r) = Bin`<$>`

f l`<*>`

f r`plate`

_ t =`pure`

t

*or*

instance`Data`

a =>`Plated`

(Tree a) where`plate`

=`uniplate`

Note the big distinction between these two implementations.

The former will only treat children directly in this tree as descendents, the latter will treat trees contained in the values under the tips also as descendants!

When in doubt, pick a `Traversal`

and just use the various `...Of`

combinators
rather than pollute `Plated`

with orphan instances!

If you want to find something unplated and non-recursive with `biplate`

use the `...OnOf`

variant with `ignored`

, though those usecases are much better served
in most cases by using the existing `Lens`

combinators! e.g.

`toListOf`

`biplate`

≡`universeOnOf`

`biplate`

`ignored`

This same ability to explicitly pass the `Traversal`

in question is why there is no
analogue to uniplate's `Biplate`

.

Moreover, since we can allow custom traversals, we implement reasonable defaults for
polymorphic data types, that only `traverse`

into themselves, and *not* their
polymorphic arguments.

## Instances

plate :: Plated a => Traversal' a a #

template :: (Data s, Typeable a) => Traversal' s a #

tinplate :: (Data s, Typeable a) => Traversal' s a #

uniplate :: Data a => Traversal' a a #

biplate :: (Data s, Typeable a) => Traversal' s a #

rewrite :: Plated a => (a -> Maybe a) -> a -> a #

Rewrite by applying a rule everywhere you can. Ensures that the rule cannot be applied anywhere in the result:

propRewrite r x =`all`

(`isNothing`

`.`

r) (`universe`

(`rewrite`

r x))

Usually `transform`

is more appropriate, but `rewrite`

can give better
compositionality. Given two single transformations `f`

and `g`

, you can
construct `a -> f a `

which performs both rewrites until a fixed point.`mplus`

g a

rewriteOf :: ASetter a b a b -> (b -> Maybe a) -> a -> b #

Rewrite by applying a rule everywhere you can. Ensures that the rule cannot be applied anywhere in the result:

propRewriteOf l r x =`all`

(`isNothing`

`.`

r) (`universeOf`

l (`rewriteOf`

l r x))

Usually `transformOf`

is more appropriate, but `rewriteOf`

can give better
compositionality. Given two single transformations `f`

and `g`

, you can
construct `a -> f a `

which performs both rewrites until a fixed point.`mplus`

g a

`rewriteOf`

::`Iso'`

a a -> (a ->`Maybe`

a) -> a -> a`rewriteOf`

::`Lens'`

a a -> (a ->`Maybe`

a) -> a -> a`rewriteOf`

::`Traversal'`

a a -> (a ->`Maybe`

a) -> a -> a`rewriteOf`

::`Setter'`

a a -> (a ->`Maybe`

a) -> a -> a

rewriteOn :: Plated a => ASetter s t a a -> (a -> Maybe a) -> s -> t #

Rewrite recursively over part of a larger structure.

`rewriteOn`

::`Plated`

a =>`Iso'`

s a -> (a ->`Maybe`

a) -> s -> s`rewriteOn`

::`Plated`

a =>`Lens'`

s a -> (a ->`Maybe`

a) -> s -> s`rewriteOn`

::`Plated`

a =>`Traversal'`

s a -> (a ->`Maybe`

a) -> s -> s`rewriteOn`

::`Plated`

a =>`ASetter'`

s a -> (a ->`Maybe`

a) -> s -> s

rewriteOnOf :: ASetter s t a b -> ASetter a b a b -> (b -> Maybe a) -> s -> t #

Rewrite recursively over part of a larger structure using a specified `Setter`

.

`rewriteOnOf`

::`Iso'`

s a ->`Iso'`

a a -> (a ->`Maybe`

a) -> s -> s`rewriteOnOf`

::`Lens'`

s a ->`Lens'`

a a -> (a ->`Maybe`

a) -> s -> s`rewriteOnOf`

::`Traversal'`

s a ->`Traversal'`

a a -> (a ->`Maybe`

a) -> s -> s`rewriteOnOf`

::`Setter'`

s a ->`Setter'`

a a -> (a ->`Maybe`

a) -> s -> s

rewriteM :: (Monad m, Plated a) => (a -> m (Maybe a)) -> a -> m a #

Rewrite by applying a monadic rule everywhere you can. Ensures that the rule cannot be applied anywhere in the result.

rewriteMOf :: Monad m => LensLike (WrappedMonad m) a b a b -> (b -> m (Maybe a)) -> a -> m b #

Rewrite by applying a monadic rule everywhere you recursing with a user-specified `Traversal`

.
Ensures that the rule cannot be applied anywhere in the result.

rewriteMOn :: (Monad m, Plated a) => LensLike (WrappedMonad m) s t a a -> (a -> m (Maybe a)) -> s -> m t #

Rewrite by applying a monadic rule everywhere inside of a structure located by a user-specified `Traversal`

.
Ensures that the rule cannot be applied anywhere in the result.

rewriteMOnOf :: Monad m => LensLike (WrappedMonad m) s t a b -> LensLike (WrappedMonad m) a b a b -> (b -> m (Maybe a)) -> s -> m t #

universe :: Plated a => a -> [a] #

Retrieve all of the transitive descendants of a `Plated`

container, including itself.

universeOf :: Getting [a] a a -> a -> [a] #

Given a `Fold`

that knows how to locate immediate children, retrieve all of the transitive descendants of a node, including itself.

`universeOf`

::`Fold`

a a -> a -> [a]

universeOn :: Plated a => Getting [a] s a -> s -> [a] #

universeOnOf :: Getting [a] s a -> Getting [a] a a -> s -> [a] #

Given a `Fold`

that knows how to locate immediate children, retrieve all of the transitive descendants of a node, including itself that lie
in a region indicated by another `Fold`

.

`toListOf`

l ≡`universeOnOf`

l`ignored`

cosmos :: Plated a => Fold a a #

Fold over all transitive descendants of a `Plated`

container, including itself.

cosmosOf :: (Applicative f, Contravariant f) => LensLike' f a a -> LensLike' f a a #

cosmosOn :: (Applicative f, Contravariant f, Plated a) => LensLike' f s a -> LensLike' f s a #

cosmosOnOf :: (Applicative f, Contravariant f) => LensLike' f s a -> LensLike' f a a -> LensLike' f s a #

transformOf :: ASetter a b a b -> (b -> b) -> a -> b #

Transform every element by recursively applying a given `Setter`

in a bottom-up manner.

`transformOf`

::`Traversal'`

a a -> (a -> a) -> a -> a`transformOf`

::`Setter'`

a a -> (a -> a) -> a -> a

transformOnOf :: ASetter s t a b -> ASetter a b a b -> (b -> b) -> s -> t #

Transform every element in a region indicated by a `Setter`

by recursively applying another `Setter`

in a bottom-up manner.

`transformOnOf`

::`Setter'`

s a ->`Traversal'`

a a -> (a -> a) -> s -> s`transformOnOf`

::`Setter'`

s a ->`Setter'`

a a -> (a -> a) -> s -> s

transformM :: (Monad m, Plated a) => (a -> m a) -> a -> m a #

Transform every element in the tree, in a bottom-up manner, monadically.

transformMOf :: Monad m => LensLike (WrappedMonad m) a b a b -> (b -> m b) -> a -> m b #

Transform every element in a tree using a user supplied `Traversal`

in a bottom-up manner with a monadic effect.

`transformMOf`

::`Monad`

m =>`Traversal'`

a a -> (a -> m a) -> a -> m a

transformMOn :: (Monad m, Plated a) => LensLike (WrappedMonad m) s t a a -> (a -> m a) -> s -> m t #

Transform every element in the tree in a region indicated by a supplied `Traversal`

, in a bottom-up manner, monadically.

`transformMOn`

:: (`Monad`

m,`Plated`

a) =>`Traversal'`

s a -> (a -> m a) -> s -> m s

transformMOnOf :: Monad m => LensLike (WrappedMonad m) s t a b -> LensLike (WrappedMonad m) a b a b -> (b -> m b) -> s -> m t #

Transform every element in a tree that lies in a region indicated by a supplied `Traversal`

, walking with a user supplied `Traversal`

in
a bottom-up manner with a monadic effect.

`transformMOnOf`

::`Monad`

m =>`Traversal'`

s a ->`Traversal'`

a a -> (a -> m a) -> s -> m s

contextsOf :: ATraversal' a a -> a -> [Context a a a] #

Return a list of all of the editable contexts for every location in the structure, recursively, using a user-specified `Traversal`

to walk each layer.

propUniverse l x =`universeOf`

l x`==`

`map`

`pos`

(`contextsOf`

l x) propId l x =`all`

(`==`

x) [`extract`

w | w <-`contextsOf`

l x]

`contextsOf`

::`Traversal'`

a a -> a -> [`Context`

a a a]

contextsOn :: Plated a => ATraversal s t a a -> s -> [Context a a t] #

Return a list of all of the editable contexts for every location in the structure in an areas indicated by a user supplied `Traversal`

, recursively using `plate`

.

`contextsOn`

b ≡`contextsOnOf`

b`plate`

`contextsOn`

::`Plated`

a =>`Traversal'`

s a -> s -> [`Context`

a a s]

contextsOnOf :: ATraversal s t a a -> ATraversal' a a -> s -> [Context a a t] #

Return a list of all of the editable contexts for every location in the structure in an areas indicated by a user supplied `Traversal`

, recursively using
another user-supplied `Traversal`

to walk each layer.

`contextsOnOf`

::`Traversal'`

s a ->`Traversal'`

a a -> s -> [`Context`

a a s]

holes :: Plated a => a -> [Pretext ((->) :: * -> * -> *) a a a] #

The one-level version of `context`

. This extracts a list of the immediate children as editable contexts.

Given a context you can use `pos`

to see the values, `peek`

at what the structure would be like with an edited result, or simply `extract`

the original structure.

propChildren x =`children`

l x`==`

`map`

`pos`

(`holes`

l x) propId x =`all`

(`==`

x) [`extract`

w | w <-`holes`

l x]

`holes`

=`holesOf`

`plate`

holesOn :: Conjoined p => Over p (Bazaar p a a) s t a a -> s -> [Pretext p a a t] #

An alias for `holesOf`

, provided for consistency with the other combinators.

`holesOn`

≡`holesOf`

`holesOn`

::`Iso'`

s a -> s -> [`Pretext`

(->) a a s]`holesOn`

::`Lens'`

s a -> s -> [`Pretext`

(->) a a s]`holesOn`

::`Traversal'`

s a -> s -> [`Pretext`

(->) a a s]`holesOn`

::`IndexedLens'`

i s a -> s -> [`Pretext`

(`Indexed`

i) a a s]`holesOn`

::`IndexedTraversal'`

i s a -> s -> [`Pretext`

(`Indexed`

i) a a s]

holesOnOf :: Conjoined p => LensLike (Bazaar p r r) s t a b -> Over p (Bazaar p r r) a b r r -> s -> [Pretext p r r t] #

Extract one level of `holes`

from a container in a region specified by one `Traversal`

, using another.

`holesOnOf`

b l ≡`holesOf`

(b`.`

l)

`holesOnOf`

::`Iso'`

s a ->`Iso'`

a a -> s -> [`Pretext`

(->) a a s]`holesOnOf`

::`Lens'`

s a ->`Lens'`

a a -> s -> [`Pretext`

(->) a a s]`holesOnOf`

::`Traversal'`

s a ->`Traversal'`

a a -> s -> [`Pretext`

(->) a a s]`holesOnOf`

::`Lens'`

s a ->`IndexedLens'`

i a a -> s -> [`Pretext`

(`Indexed`

i) a a s]`holesOnOf`

::`Traversal'`

s a ->`IndexedTraversal'`

i a a -> s -> [`Pretext`

(`Indexed`

i) a a s]

deep :: (Conjoined p, Applicative f, Plated s) => Traversing p f s s a b -> Over p f s s a b #

Try to apply a traversal to all transitive descendants of a `Plated`

container, but
do not recurse through matching descendants.

`deep`

::`Plated`

s =>`Fold`

s a ->`Fold`

s a`deep`

::`Plated`

s =>`IndexedFold`

s a ->`IndexedFold`

s a`deep`

::`Plated`

s =>`Traversal`

s s a b ->`Traversal`

s s a b`deep`

::`Plated`

s =>`IndexedTraversal`

s s a b ->`IndexedTraversal`

s s a b

composOpFold :: Plated a => b -> (b -> b -> b) -> (a -> b) -> a -> b #

Fold the immediate children of a `Plated`

container.

`composOpFold`

z c f =`foldrOf`

`plate`

(c`.`

f) z