Data.Generics.Zipper

``Scrap Your Zippers: A Generic Zipper for Heterogeneous Types. Michael D. Adams. WGP '10: Proceedings of the 2010 ACM SIGPLAN workshop on Generic programming, 2010.''

See http://www.cs.indiana.edu/~adamsmd/papers/scrap_your_zippers/

Core types

data Zipper root

A generic zipper with a root object of type root.

Core interface

Injection and projection

toZipper :: Data a => a -> Zipper a

Create a zipper. The focus starts at the root of the object.

fromZipper :: Zipper a -> a

Move up a zipper to the root and return the root object.

Basic movement

left :: Zipper a -> Maybe (Zipper a)

Move left. Returns Nothing iff already at leftmost sibling.

right :: Zipper a -> Maybe (Zipper a)

Move right. Returns Nothing iff already at rightmost sibling.

down :: Zipper a -> Maybe (Zipper a)

Move down. Moves to rightmost immediate child. Returns Nothing iff at a leaf and thus no children exist.

down' :: Zipper a -> Maybe (Zipper a)

Move down. Move to the leftmost immediate child. Returns Nothing iff at a leaf and thus no children exist.

up :: Zipper a -> Maybe (Zipper a)

Move up. Returns Nothing iff already at root and thus no parent exists.

Basic hole manipulation

query :: GenericQ b -> Zipper a -> b

Apply a generic query to the hole.

trans :: GenericT -> Zipper a -> Zipper a

Apply a generic transformation to the hole.

transM :: Monad m => GenericM m -> Zipper a -> m (Zipper a)

Apply a generic monadic transformation to the hole

Convenience hole manipulation interface

getHole :: Typeable b => Zipper a -> Maybe b

Get the value in the hole. Returns Nothing iff a is not the type of the value in the hole.

setHole :: Typeable a => a -> Zipper b -> Zipper b

Set the value in the hole. Does nothing iff a is not the type of the value in the hole.

setHole' :: Typeable a => a -> Zipper b -> Maybe (Zipper b)

Set the value in the hole. Returns Nothing iff a is not the type of the value in the hole.

Generic zipper traversals

Traversal helpers

Query

moveQ

Arguments

:: Move a

Move operation

-> b

Default if can't move

-> (Zipper a -> b)

Query if can move

-> Zipper a

Zipper

-> b

Apply a generic query using the specified movement operation.

leftQ

Arguments

:: b

Value to return of no left sibling exists.

-> (Zipper a -> b)

-> Zipper a

-> b

Apply a generic query to the left sibling if one exists.

rightQ

Arguments

:: b

Value to return if no right sibling exists.

-> (Zipper a -> b)

-> Zipper a

-> b

Apply a generic query to the right sibling if one exists.

downQ

Arguments

:: b

Value to return if no children exist.

-> (Zipper a -> b)

-> Zipper a

-> b

Apply a generic query to the parent if it exists.

upQ

Arguments

:: b

Value to return if parent does not exist.

-> (Zipper a -> b)

-> Zipper a

-> b

Apply a generic query to the rightmost child if one exists.

Transform

moveT

Arguments

:: Move a

Move to

-> Move a

Move back

-> Zipper a

Default if can't move

-> (Zipper a -> Zipper a)

Transformer if can move

-> Zipper a

Zipper

-> Zipper a

Apply a generic transformer using the specified movement operations.

leftT :: (Zipper a -> Zipper a) -> Zipper a -> Zipper a

Apply a generic transformer to the left sibling if one exists. Otherwise, leaves the zipper unchanged.

rightT :: (Zipper a -> Zipper a) -> Zipper a -> Zipper a

Apply a generic transformer to the right sibling if one exists. Otherwise, leaves the zipper unchanged.

downT :: (Zipper a -> Zipper a) -> Zipper a -> Zipper a

Apply a generic transformer to the rightmost child if one exists. Otherwise, leaves the zipper unchanged.

upT :: (Zipper a -> Zipper a) -> Zipper a -> Zipper a

Apply a generic transformer to the parent if it exists. Otherwise, leaves the zipper unchanged.

Monadic Transform

moveM

Arguments

:: Monad m

=> Move a

Move to

-> Move a

Move back

-> m (Zipper a)

Default if can't move

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

Monadic transformer if can move

-> Zipper a

Zipper

-> m (Zipper a)

Apply a generic monadic transformer using the specified movement operations.

rightM

Arguments

:: Monad m

=> m (Zipper a)

Value to return if no right sibling exists.

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

-> Zipper a

-> m (Zipper a)

Apply a generic monadic transformer to the right sibling if one exists.

downM

Arguments

:: Monad m

=> m (Zipper a)

Value to return if no children exist.

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

-> Zipper a

-> m (Zipper a)

Apply a generic monadic transformer to the rightmost child if one exists.

upM

Arguments

:: Monad m

=> m (Zipper a)

Value to return if parent does not exist.

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

-> Zipper a

-> m (Zipper a)

Apply a generic monadic transformer to the parent if it exists.

Movement

leftmost :: Zipper a -> Zipper a

Move to the leftmost sibling.

rightmost :: Zipper a -> Zipper a

Move to the rightmost sibling.

Map traversals

zmapQ :: GenericQ b -> Zipper a -> [b]

Apply a generic query to the immediate children.

zmapT :: GenericT -> Zipper a -> Zipper a

Apply a generic transformation to the immediate children.

zmapM :: Monad m => GenericM m -> Zipper a -> m (Zipper a)

Apply a generic monadic transformation to the immediate children.

zmapMp :: MonadPlus m => GenericM m -> Zipper a -> m (Zipper a)

Apply a generic monadic transformation to at least one child that does not fail.

Tree traversals

zeverywhere :: GenericT -> Zipper a -> Zipper a

Apply a generic transformation everywhere in a bottom-up manner.

zeverywhere' :: GenericT -> Zipper a -> Zipper a

Apply a generic transformation everywhere in a top-down manner.

zsomewhere :: MonadPlus m => GenericM m -> Zipper a -> m (Zipper a)

Apply a generic monadic transformation once at the topmost leftmost successful location.

zreduce :: GenericM Maybe -> Zipper a -> Zipper a

Repeatedly apply a monadic Maybe generic transformation at the top-most, left-most position that the transformation returns Just. Behaves like iteratively applying zsomewhere but is more efficient because it re-evaluates the transformation at only the parents of the last successful application.