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

Uniplate

class Plated a whereSource

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.

Methods

plate :: Traversal' a aSource

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 [a]
Plated (Tree a)

Uniplate Combinators

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

Extract the immediate descendants of a Plated container.

 children ≡ toListOf plate

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

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

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

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

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 aSource

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 aSource

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 tSource

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 tSource

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]Source

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

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

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]Source

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 a -> Getting [a] a a -> s -> [a]Source

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

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

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

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

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 aSource

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 aSource

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 tSource

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

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]Source

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]Source

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]Source

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]Source

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]Source

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]Source

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]Source

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

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

 para ≡ paraOf plate

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

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

Fold the immediate children of a Plated container.

 composOpFold z c f = foldrOf plate (c . f) z

Parts

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

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!