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


-- | Generic zipper for systems of recursive datatypes
--   
--   The Zipper is a data structure that allows typed navigation on a
--   value. It maintains a subterm as a current point of focus. The rest of
--   the value is the context. Focus and context are automatically updated
--   when navigating up, down, left or right in the value. The term that is
--   in focus can also be modified.
--   
--   This library offers a generic Zipper for systems of datatypes. In
--   particular, it is possible to move the focus between subterms of
--   different types, in an entirely type-safe way. This library is built
--   on top of the multirec library, so all that is required to get a
--   Zipper for a datatype system is to instantiate the multirec library
--   for that system.
@package zipper
@version 0.1


-- | The generic zipper.
module Generics.MultiRec.Zipper

-- | Abstract type of locations. A location contains the current focus and
--   its context. A location is parameterized over the system of datatypes
--   and over the type of the complete value.
data Loc :: (* -> *) -> (* -> *) -> * -> *

-- | Abstract type of context frames. Not required for the high-level
--   navigation functions.

-- | It is in general not necessary to use the generic navigation functions
--   directly. The functions listed in the `Interface' section below are
--   more user-friendly.
class (HFunctor f) => Zipper f
cmap :: (Zipper f) => (forall b. (Ix s b) => s b -> r b -> r' b) -> Ctx f s r ix b -> Ctx f s r' ix b
fill :: (Zipper f, Ix s b) => Ctx f s r ix b -> r b -> f s r ix
first :: (Zipper f) => (forall b. (Ix s b) => r b -> Ctx f s r ix b -> a) -> f s r ix -> Maybe a
last :: (Zipper f) => (forall b. (Ix s b) => r b -> Ctx f s r ix b -> a) -> f s r ix -> Maybe a
next :: (Zipper f) => (forall b. (Ix s b) => r b -> Ctx f s r ix b -> a) -> (Ix s b) => Ctx f s r ix b -> r b -> Maybe a
prev :: (Zipper f) => (forall b. (Ix s b) => r b -> Ctx f s r ix b -> a) -> (Ix s b) => Ctx f s r ix b -> r b -> Maybe a

-- | Start navigating a datastructure. Returns a location that focuses the
--   entire value and has an empty context.
enter :: (Ix s ix, Zipper (PF s)) => s ix -> ix -> Loc s I0 ix

-- | Move down to the leftmost child. Returns <a>Nothing</a> if the current
--   focus is a leaf.
down :: Loc s I0 ix -> Maybe (Loc s I0 ix)

-- | Move down to the rightmost child. Returns <a>Nothing</a> if the
--   current focus is a leaf.
down' :: Loc s I0 ix -> Maybe (Loc s I0 ix)

-- | Move up to the parent. Returns <a>Nothing</a> if the current focus is
--   the root.
up :: Loc s I0 ix -> Maybe (Loc s I0 ix)

-- | Move to the right sibling. Returns <a>Nothing</a> if the current focus
--   is the rightmost sibling.
right :: Loc s r ix -> Maybe (Loc s r ix)

-- | Move to the left sibling. Returns <a>Nothing</a> if the current focus
--   is the leftmost sibling.
left :: Loc s r ix -> Maybe (Loc s r ix)

-- | Move through all positions in depth-first left-to-right order.
dfnext :: Loc s I0 ix -> Maybe (Loc s I0 ix)

-- | Move through all positions in depth-first right-to-left order.
dfprev :: Loc s I0 ix -> Maybe (Loc s I0 ix)

-- | Return the entire value, independent of the current focus.
leave :: Loc s I0 ix -> ix

-- | Operate on the current focus. This function can be used to extract the
--   current point of focus.
on :: (forall xi. (Ix s xi) => s xi -> r xi -> a) -> Loc s r ix -> a

-- | Update the current focus without changing its type.
update :: (forall xi. (Ix s xi) => s xi -> xi -> xi) -> Loc s I0 ix -> Loc s I0 ix

-- | Most general eliminator. Both <a>on</a> and <a>update</a> can be
--   defined in terms of <a>foldZipper</a>.
foldZipper :: (forall xi. (Ix s xi) => s xi -> xi -> r xi) -> Algebra s r -> Loc s I0 ix -> r ix
instance (Constructor c, Zipper f) => Zipper (C c f)
instance (Zipper f) => Zipper (f :>: xi)
instance (Zipper f, Zipper g) => Zipper (f :*: g)
instance (Zipper f, Zipper g) => Zipper (f :+: g)
instance Zipper U
instance Zipper (K a)
instance Zipper (I xi)