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


-- | Generic zipper for families 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 families 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 family is to instantiate the multirec library
--   for that family.
@package zipper
@version 0.2


-- | 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 family 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 phi f) => Zipper phi f
cmapA :: (Zipper phi f, Applicative a) => (forall ix. phi ix -> r ix -> a (r' ix)) -> Ctx f b r ix -> a (Ctx f b r' ix)
fill :: (Zipper phi f) => phi b -> Ctx f b r ix -> r b -> f r ix
first :: (Zipper phi f) => (forall b. phi b -> r b -> Ctx f b r ix -> a) -> f r ix -> Maybe a
last :: (Zipper phi f) => (forall b. phi b -> r b -> Ctx f b r ix -> a) -> f r ix -> Maybe a
next :: (Zipper phi f) => (forall b. phi b -> r b -> Ctx f b r ix -> a) -> phi b -> Ctx f b r ix -> r b -> Maybe a
prev :: (Zipper phi f) => (forall b. phi b -> r b -> Ctx f b r ix -> a) -> phi b -> Ctx f b r ix -> r b -> Maybe a

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

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

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

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

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

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

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

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

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

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

-- | Update the current focus without changing its type.
update :: (forall xi. phi xi -> xi -> xi) -> Loc phi I0 ix -> Loc phi 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. phi xi -> xi -> r xi) -> Algebra phi r -> Loc phi I0 ix -> r ix
instance (Constructor c, Zipper phi f) => Zipper phi (C c f)
instance (Zipper phi f) => Zipper phi (f :>: xi)
instance (Zipper phi f, Zipper phi g) => Zipper phi (f :*: g)
instance (Zipper phi f, Zipper phi g) => Zipper phi (f :+: g)
instance Zipper phi U
instance Zipper phi (K a)
instance (El phi xi) => Zipper phi (I xi)
instance HFunctor phi (Loc phi)
instance (Zipper phi (PF phi)) => HFunctor phi (Ctxs phi b)
instance (Zipper phi f) => HFunctor phi (Ctx f b)