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


-- | A Potentially-Excellent Zipper library
--   
--   PEZ is a generic zipper library. It uses lenses from the
--   <a>fclabels</a> package to reference a <a>location</a> to move to in
--   the zipper. The zipper is restricted to types in the Typeable class,
--   allowing the user to <a>move up</a> through complex data structures
--   such as mutually-recursive types.
--   
--   Both the Typeable class and fclabels lenses can be derived in GHC,
--   making it easy for the programmer to use a zipper with a minimum of
--   boilerplate.
--   
--   First import the library, which brings in the Typeable and fclabels
--   modules. You will also want to enable a few extensions:
--   
--   <pre>
--   -- Put these in a LANGUAGE pragma:
--   -- TemplateHaskell, DeriveDataTypeable, TypeOperators
--   module Main where
--   
--   import Data.Typeable.Zipper
--   </pre>
--   
--   Create a datatype, deriving an instance of the Typeable class, and
--   generate a lens using functions from fclabels:
--   
--   <pre>
--   data Tree a = Node
--       _leftNode :: Tree a
--     , _val      :: a
--     , _rightNode :: Tree a
--     | Nil
--     deriving (Typeable,Show)
--   
--   $(mkLabelsNoTypes [''Tree])
--   </pre>
--   
--   Now we can go crazy using Tree in a Zipper:
--   
--   <pre>
--   treeBCD = Node (Node Nil 'b' Nil) 'c' (Node Nil 'd' Nil)
--   
--   descendLeft :: Zipper1 (Tree a) -&gt; Zipper1 (Tree a)
--   descendLeft z = case (viewf z) of
--                        Nil -&gt; z
--                        _   -&gt; descendLeft $ moveTo leftNode z
--   
--   insertLeftmost :: a -&gt; Tree a -&gt; Tree a
--   insertLeftmost x = close . setL focus x . descendLeft . zipper
--   
--   treeABCD = insertLeftmost 'a' treeBCD
--   </pre>
--   
--   Because of the flexibility of fclabels, this zipper library can be
--   used to express moving about in reversible computations simply by
--   defining such a lens, for instance:
--   
--   <pre>
--   stringRep :: (Show b, Read b) =&gt; b :-&gt; String
--   stringRep = lens show (const . read)
--   </pre>
--   
--   Please send any feature requests or bug reports along.
@package pez
@version 0.0.4

module Data.Typeable.Zipper
data Zipper a b
zipper :: a -> Zipper a a
close :: Zipper a b -> a

-- | Types of the ZPath class act as references to <a>paths</a> down
--   through a datatype. Currently lenses from <tt>fclabels</tt> and
--   SavedPath types are instances
class ZPath p
moveTo :: (ZPath p, Typeable b, Typeable c) => p b c -> Zipper a b -> Zipper a c

-- | Move up n levels as long as the type of the parent is what the
--   programmer is expecting and we aren't already at the top. Otherwise
--   return Nothing.
moveUp :: (Typeable c, Typeable b) => Int -> Zipper a c -> Maybe (Zipper a b)
focus :: :-> (Zipper a1 a) a

-- | a view function for a Zipper's focus. Defined simply as: <a>getL</a>
--   focus
viewf :: Zipper a b -> b

-- | returns True if Zipper is at the top level of the data structure:
atTop :: Zipper a b -> Bool

-- | stores the path used to return to the same location in a data
--   structure as the one we just exited. You can also extract a lens from
--   a SavedPath that points to that location:
data SavedPath a b

-- | Return a SavedPath type encapsulating the current location in the
--   Zipper. This lets you return to a location in your data type after
--   closing the Zipper.
save :: Zipper a b -> SavedPath a b

-- | return a SavedPath from n levels up to the current level
saveFromAbove :: (Typeable c, Typeable b) => Int -> Zipper a c -> Maybe (SavedPath b c)

-- | Extract a composed lens that points to the location we SavedPath. This
--   lets us modify, set or get a location that we visited with our Zipper
--   after closing the Zipper.
savedLens :: (Typeable a, Typeable b) => SavedPath a b -> (a :-> b)
closeSaving :: Zipper a b -> (SavedPath a b, a)

-- | Move up a level as long as the type of the parent is what the
--   programmer is expecting and we aren't already at the top. Otherwise
--   return Nothing.
moveUpSaving :: (Typeable c, Typeable b) => Int -> Zipper a c -> Maybe (Zipper a b, SavedPath b c)

-- | Return to a previously SavedPath location within a data-structure.
--   Saving and restoring lets us for example: find some location within
--   our structure using a Zipper, save the location, fmap over the entire
--   structure, and then return to where we were:
restore :: (ZPath p, Typeable a, Typeable b) => p a b -> a -> Zipper a b

-- | a simple type synonym for a Zipper where the type at the focus is the
--   same as the type of the outer (unzippered) type. Cleans up type
--   signatures for simple recursive types:
type Zipper1 a = Zipper a a

-- | <a>moveTo</a> with arguments flipped. Operator plays on the idea of
--   addition of levels onto the focus.
(.+) :: (ZPath p, Typeable b, Typeable c) => Zipper a b -> p b c -> Zipper a c

-- | setL focus, with arguments flipped
(.>) :: Zipper a b -> b -> Zipper a b

-- | <a>moveUp</a> with arguments flipped. Operator syntax comes from the
--   idea of moving up as subtraction.
(.-) :: (Typeable c, Typeable b) => Zipper a c -> Int -> Maybe (Zipper a b)
(?+) :: (ZPath p, Typeable b, Typeable c) => Maybe (Zipper a b) -> p b c -> Maybe (Zipper a c)
(?>) :: Maybe (Zipper a b) -> b -> Maybe (Zipper a b)
(?-) :: (Typeable c, Typeable b) => Maybe (Zipper a c) -> Int -> Maybe (Zipper a b)

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable a
instance ZPath SavedPath
instance ZPath :->
instance Typeable2 Zipper
instance Typeable2 SavedPath
instance Category SavedPath