lens-3.8.7.3: Lenses, Folds and Traversals

Portability | Rank2Types
Stability | provisional
Maintainer | Edward Kmett <ekmett@gmail.com>
Safe Haskell | Trustworthy

Control.Lens.Plated

Contents

- Uniplate
- Uniplate Combinators
- Compos
- Parts

Description

The name "plate" stems originally from "boilerplate", which was the term used by the "Scrap Your Boilerplate" papers, and later inherited by Neil Mitchell's "Uniplate".

http://community.haskell.org/~ndm/uniplate/

The combinators in here are designed to be compatible with and subsume the `uniplate` API with the notion of a `Traversal` replacing a `uniplate` or `biplate`.

By implementing these combinators in terms of `plate` instead of `uniplate` additional type safety is gained, as the user is no longer responsible for maintaining invariants such as the number of children they received.

Note: The `Biplate` is deliberately excluded from the API here, with the intention that you replace them with either explicit traversals, or by using the `On` variants of the combinators below with `biplate` from `Data.Data.Lens`. As a design, it forced the user into too many situations where they had to choose between correctness and ease of use, and it was brittle in the face of competing imports.

The sensible use of these combinators makes some simple assumptions. Notably, any of the `On` combinators are expecting a `Traversal`, `Setter` or `Fold` to play the role of the `biplate` combinator, and so when the types of the contents and the container match, they should be the `id` `Traversal`, `Setter` or `Fold`.

It is often beneficial to use the combinators in this module with the combinators from `Data.Data.Lens` or `GHC.Generics.Lens` to make it easier to automatically derive definitions for `plate`, or to derive custom traversals.

Synopsis

- class Plated a where
  - plate :: Traversal' a a
- children :: Plated a => a -> [a]
- rewrite :: Plated a => (a -> Maybe a) -> a -> a
- rewriteOf :: ASetter' a a -> (a -> Maybe a) -> a -> a
- rewriteOn :: Plated a => ASetter s t a a -> (a -> Maybe a) -> s -> t
- rewriteOnOf :: ASetter s t a a -> ASetter' a a -> (a -> Maybe a) -> s -> t
- rewriteM :: (Monad m, Plated a) => (a -> m (Maybe a)) -> a -> m a
- rewriteMOf :: Monad m => LensLike' (WrappedMonad m) a a -> (a -> m (Maybe a)) -> a -> m a
- 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 a -> LensLike' (WrappedMonad m) a a -> (a -> m (Maybe a)) -> s -> m t
- universe :: Plated a => a -> [a]
- universeOf :: Getting [a] a b a b -> a -> [a]
- universeOn :: Plated a => Getting [a] s t a a -> s -> [a]
- universeOnOf :: Getting [a] s t a b -> Getting [a] a b a b -> s -> [a]
- transform :: Plated a => (a -> a) -> a -> a
- transformOf :: ASetter' a a -> (a -> a) -> a -> a
- transformOn :: Plated a => ASetter s t a a -> (a -> a) -> s -> t
- transformOnOf :: ASetter s t a a -> ASetter' a a -> (a -> a) -> s -> t
- transformM :: (Monad m, Plated a) => (a -> m a) -> a -> m a
- transformMOf :: Monad m => LensLike' (WrappedMonad m) 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
- transformMOnOf :: Monad m => LensLike (WrappedMonad m) s a a a -> LensLike' (WrappedMonad m) a a -> (a -> m a) -> s -> m a
- 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 => Overloading 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 -> Overloading 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 b a b -> (a -> [r] -> r) -> a -> r
- composOpFold :: Plated a => b -> (b -> b -> b) -> (a -> b) -> a -> b
- parts :: Plated a => Lens' a [a]

# Uniplate

class Plated a where

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.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.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.

Methods

plate :: Traversal' a a

`Traversal` of the immediate children of this structure.

If you're using GHC 7.2 or newer and your type has a `Data` instance, `plate` will default to `uniplate` and you can choose to not override it with your own definition.

Instances

Plated Exp |
Plated Pat |
Plated Type |
Plated Dec |
Plated Stmt |
Plated Con |
Plated Kind |
Plated [a] |
Plated (Tree a) |

# Uniplate Combinators

children :: Plated a => a -> [a]

Extract the immediate descendants of a `Plated` container.

     children ≡ toListOf plate

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 `mplus` g a` which performs both rewrites until a fixed point.

rewriteOf :: ASetter' a 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:

     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 `mplus` g a` which performs both rewrites until a fixed point.

     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 a -> ASetter' a a -> (a -> Maybe a) -> s -> t

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

     rewriteOnOf :: Plated a => Iso' s a       -> Iso' a a       -> (a -> Maybe a) -> s -> s
     rewriteOnOf :: Plated a => Lens' s a      -> Lens' a a      -> (a -> Maybe a) -> s -> s
     rewriteOnOf :: Plated a => Traversal' s a -> Traversal' a a -> (a -> Maybe a) -> s -> s
     rewriteOnOf :: Plated a => 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 a -> (a -> m (Maybe a)) -> a -> m a

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 a -> LensLike' (WrappedMonad m) 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`, using a user-specified `Traversal` for recursion. Ensures that the rule cannot be applied anywhere in the result.

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

Retrieve all of the transitive descendants of a `Plated` container, including itself.

universeOf :: Getting [a] a b a b -> 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 t a a -> s -> [a]

Given a `Fold` that knows how to find `Plated` parts of a container retrieve them and all of their descendants, recursively.

universeOnOf :: Getting [a] s t a b -> Getting [a] a b a b -> 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

transform :: Plated a => (a -> a) -> a -> a

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

For example, replacing negative literals with literals:

     negLits = transform $ \x -> case x of
       Neg (Lit i) -> Lit (negate i)
       _           -> x

transformOf :: ASetter' a a -> (a -> a) -> a -> a

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

transformOn :: Plated a => ASetter s t a a -> (a -> a) -> s -> t

Transform every element in the tree in a bottom-up manner over a region indicated by a `Setter`.

     transformOn :: Plated a => Traversal' s a -> (a -> a) -> s -> s
     transformOn :: Plated a => Setter' s a    -> (a -> a) -> s -> s

transformOnOf :: ASetter s t a a -> ASetter' a a -> (a -> a) -> 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 a -> (a -> m a) -> a -> m a

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 a a a -> LensLike' (WrappedMonad m) a a -> (a -> m a) -> s -> m a

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

contexts :: Plated a => a -> [Context a a a]

Return a list of all of the editable contexts for every location in the structure, recursively.

     propUniverse x = universe x == map pos (contexts x)
     propId x = all (== x) [extract w | w <- contexts x]

     contexts ≡ contextsOf plate

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]

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 => Overloading 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 -> Overloading 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]

para :: Plated a => (a -> [r] -> r) -> a -> r

Perform a fold-like computation on each value, technically a paramorphism.

     para ≡ paraOf plate

paraOf :: Getting (Endo [a]) a b a b -> (a -> [r] -> r) -> a -> r

Perform a fold-like computation on each value, technically a paramorphism.

     paraOf :: Fold a a -> (a -> [r] -> r) -> a -> r

# Compos

Provided for compatibility with Björn Bringert's `compos` library.

Note: Other operations from compos that were inherited by `uniplate` are not included to avoid having even more redundant names for the same operators. For comparison:

     composOpMonoid ≡ foldMapOf plate
     composOpMPlus f ≡ msumOf (plate . to f)
     composOp ≡ descend ≡ over plate
     composOpM ≡ descendM ≡ mapMOf plate
     composOpM_ ≡ descendM_ ≡ mapMOf_ plate

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

# Parts

parts :: Plated a => Lens' a [a]

The original `uniplate` combinator, implemented in terms of `Plated` as a `Lens`.

     parts ≡ partsOf plate

The resulting `Lens` is safer to use as it ignores 'over-application' and deals gracefully with under-application, but it is only a proper `Lens` if you don't change the list `length`!