-----------------------------------------------------------------------------
-- |
-- Module      :  Control.Lens.Zipper
-- Copyright   :  (C) 2012-13 Edward Kmett
-- License     :  BSD-style (see the file LICENSE)
-- Maintainer  :  Edward Kmett <ekmett@gmail.com>
-- Stability   :  experimental
-- Portability :  non-portable
--
-- This module provides a 'Zipper' with fairly strong type checking guarantees.
--
-- The code here is inspired by Brandon Simmons' @zippo@ package, but uses
-- a different approach to represent the 'Zipper' that makes the whole thing
-- look like his breadcrumb trail, and can move side-to-side through
-- traversals.
--
-- Some examples types:
--
-- [@'Top' ':>>' a@] represents a trivial 'Zipper' with its focus at the root.
--
-- [@'Top' ':>>' 'Data.Tree.Tree' a ':>>' a@] represents a 'Zipper' that starts with a
--   'Data.Tree.Tree' and descends in a single step to values of type @a@.
--
-- [@'Top' ':>>' 'Data.Tree.Tree' a ':>>' 'Data.Tree.Tree' a ':>>' 'Data.Tree.Tree' a@] represents a 'Zipper' into a
--   'Data.Tree.Tree' with an intermediate bookmarked 'Data.Tree.Tree',
--   focusing in yet another 'Data.Tree.Tree'.
--
-- Since individual levels of a 'Zipper' are managed by an arbitrary
-- 'Control.Lens.Type.IndexedTraversal', you can move left and right through
-- the 'Control.Lens.Type.IndexedTraversal' selecting neighboring elements.
--
-- >>> zipper ("hello","world") & downward _1 & fromWithin traverse & focus .~ 'J' & rightmost & focus .~ 'y' & rezip
-- ("Jelly","world")
--
-- This is particularly powerful when compiled with 'Control.Lens.Plated.plate',
-- 'Data.Data.Lens.uniplate' or 'Data.Data.Lens.biplate' for walking down into
-- self-similar children in syntax trees and other structures.
--
-- Given keys in ascending order you can jump directly to a given key with
-- 'moveTo'. When used with traversals for balanced
-- tree-like structures such as an 'Data.IntMap.IntMap' or 'Data.Map.Map',
-- searching for a key with 'moveTo' can be done in logarithmic time.
-----------------------------------------------------------------------------
module Control.Lens.Zipper
  (
  -- * Zippers
    Top()
  , (:>)()
  , (:>>)()
  , (:@)()
  , Zipper
  , zipper
  -- ** Focusing
  , focus
  , focusedContext
  -- ** Vertical Movement
  , upward
  , downward, idownward
  , within, iwithin
  , withins, iwithins
  -- ** Lateral Movement
  , leftward, rightward
  , leftmost, rightmost
  -- ** Movement Combinators
  , tug
  , tugs
  , jerks
  , farthest
  -- ** Absolute Positioning
  , tooth
  , teeth
  , jerkTo
  , tugTo
  , moveTo
  , moveToward
  -- ** Closing the zipper
  , rezip
  , Zipped
  , Zipping()
  -- ** Recording
  , Tape()
  , saveTape
  , restoreTape
  , restoreNearTape
  -- ** Unsafe Movement
  , fromWithin
  , ifromWithin
  , unsafelyRestoreTape
  ) where

import Control.Lens.Internal.Zipper

-- $setup
-- >>> :set -XNoOverloadedStrings
-- >>> import Control.Lens