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


-- | Traversal based zippers
--   
--   Traversal based zippers.
@package zippers
@version 0.2.5


-- | This module provides internal types and functions used in the
--   implementation of <tt>Control.Zipper</tt>. You shouldn't need to
--   import it directly, and the exported types can be used to break
--   <a>Zipper</a> invariants.
module Control.Zipper.Internal

-- | A <a>Jacket</a> is used to store the contents of a <a>Traversal</a> in
--   a way that we do not have to re-asocciate the elements. This enables
--   us to more gracefully deal with infinite traversals.
data Jacket i a
Ap :: Int -> Bool -> Bool -> (Last i) -> (Jacket i a) -> (Jacket i a) -> Jacket i a
Leaf :: i -> a -> Jacket i a
Pure :: Jacket i a

-- | Return the number of children in a jacket
size :: Jacket i a -> Int

-- | This is an internal function used to check from left-to-right if a
--   <a>Jacket</a> has any <a>Leaf</a> nots or not.
nullLeft :: Jacket i a -> Bool

-- | This is an internal function used to check from right-to-left if a
--   <a>Jacket</a> has any <a>Leaf</a> nots or not.
nullRight :: Jacket i a -> Bool

-- | This is used to extract the maximal key from a <a>Jacket</a>. This is
--   used by <a>moveTo</a> and <a>moveToward</a> to seek specific keys,
--   borrowing the asympotic guarantees of the original structure in many
--   cases!
maximal :: Jacket i a -> Last i

-- | This is an illegal <a>Monoid</a>.

-- | Construct a <a>Jacket</a> from a <a>Bazaar</a>
jacketIns :: Bazaar (Indexed i) a b t -> Jacket i a

-- | Once we've updated a <a>Zipper</a> we need to put the values back into
--   the original shape. <a>Flow</a> is an illegal <a>Applicative</a> that
--   is used to put the values back.
newtype Flow i b a
Flow :: (Jacket i b -> a) -> Flow i b a
[runFlow] :: Flow i b a -> Jacket i b -> a

-- | This is an illegal <a>Applicative</a>.

-- | Given a <a>Bazaar</a> and a <a>Jacket</a> build from that
--   <a>Bazaar</a> with <a>jacketIns</a>, refill the <a>Bazaar</a> with its
--   new contents.
jacketOuts :: Bazaar (Indexed i) a b t -> Jacket j b -> t

-- | This is only a valid <a>Lens</a> if you don't change the shape of the
--   <a>Jacket</a>!
jacket :: AnIndexedTraversal i s t a b -> Lens s t (Jacket i a) (Jacket j b)

-- | A <a>Path</a> into a <a>Jacket</a> that ends at a <a>Leaf</a>.
data Path i a
ApL :: Int -> Bool -> Bool -> (Last i) -> !(Path i a) -> !(Jacket i a) -> Path i a
ApR :: Int -> Bool -> Bool -> (Last i) -> !(Jacket i a) -> !(Path i a) -> Path i a
Start :: Path i a

-- | Calculate the absolute position of the <a>Leaf</a> targeted by a
--   <a>Path</a>.
--   
--   This can be quite expensive for right-biased traversals such as you
--   receive from a list.
offset :: Path i a -> Int

-- | Return the total number of children in the <a>Jacket</a> by walking
--   the <a>Path</a> to the root.
pathsize :: Path i a -> Int

-- | Reconstruct a <a>Jacket</a> from a <a>Path</a>.
recompress :: Path i a -> i -> a -> Jacket i a

-- | Walk down the tree to the leftmost child.
startl :: Path i a -> Jacket i a -> r -> (Path i a -> i -> a -> r) -> r

-- | Walk down the tree to the rightmost child.
startr :: Path i a -> Jacket i a -> r -> (Path i a -> i -> a -> r) -> r

-- | Move left one <a>Leaf</a>.
movel :: Path i a -> Jacket i a -> r -> (Path i a -> i -> a -> r) -> r

-- | Move right one <a>Leaf</a>.
mover :: Path i a -> Jacket i a -> r -> (Path i a -> i -> a -> r) -> r

-- | This is used to represent the <a>Top</a> of the <a>Zipper</a>.
--   
--   Every <a>Zipper</a> starts with <a>Top</a>.
--   
--   <i>e.g.</i> <tt><a>Top</a> <a>:&gt;&gt;</a> a</tt> is the type of the
--   trivial <a>Zipper</a>.
data Top

-- | This is the type of a <a>Zipper</a>. It visually resembles a
--   "breadcrumb trail" as used in website navigation. Each breadcrumb in
--   the trail represents a level you can move up to.
--   
--   This type operator associates to the left, so you can use a type like
--   
--   <pre>
--   <a>Top</a> <a>:&gt;&gt;</a> (<a>String</a>,<a>Double</a>) <a>:&gt;&gt;</a> <a>String</a> <a>:&gt;&gt;</a> <a>Char</a>
--   </pre>
--   
--   to represent a <a>Zipper</a> from
--   <tt>(<a>String</a>,<a>Double</a>)</tt> down to <a>Char</a> that has an
--   intermediate crumb for the <a>String</a> containing the <a>Char</a>.
--   
--   You can construct a <a>Zipper</a> into *any* data structure with
--   <a>zipper</a>.
--   
--   You can repackage up the contents of a <a>Zipper</a> with
--   <a>rezip</a>.
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper 42
--   42
--   </pre>
--   
--   The combinators in this module provide lot of things you can do to the
--   <a>Zipper</a> while you have it open.
--   
--   Note that a value of type <tt>h <a>:&gt;</a> s <a>:&gt;</a> a</tt>
--   doesn't actually contain a value of type <tt>h <a>:&gt;</a> s</tt> --
--   as we descend into a level, the previous level is unpacked and stored
--   in <a>Coil</a> form. Only one value of type <tt>_ <a>:&gt;</a> _</tt>
--   exists at any particular time for any particular <a>Zipper</a>.
data Zipper h i a
Zipper :: !(Coil h i a) -> Int -> !Int -> !(Path i a) -> i -> a -> Zipper h i a

-- | An empty data type, used to represent the pairing of a position in a
--   <a>Zipper</a> with an index. See <a>:&gt;</a>.
data (:@) a i

-- | This type family represents a <a>Zipper</a> with the <tt>p</tt>
--   variable abstracting over the position and the index, in terms of
--   <a>:@</a>. You can visually see it in type signatures as:
--   
--   <pre>
--   h <a>:&gt;</a> (a <a>:@</a> i) = <a>Zipper</a> h i a
--   </pre>

-- | Many zippers are indexed by Int keys. This type alias is convenient
--   for reducing syntactic noise for talking about these boring indices.
type h :>> a = Zipper h Int a

-- | This represents the type a <a>Zipper</a> will have when it is fully
--   <a>Zipped</a> back up.

-- | A <a>Coil</a> is a linked list of the levels above the current one.
--   The length of a <a>Coil</a> is known at compile time.
--   
--   This is part of the internal structure of a <a>Zipper</a>. You
--   shouldn't need to manipulate this directly.
data Coil t i a
[Coil] :: Coil Top Int a
[Snoc] :: Ord i => !(Coil h j s) -> AnIndexedTraversal' i s a -> Int -> !Int -> !(Path j s) -> j -> (Jacket i a -> s) -> Coil (Zipper h j s) i a

-- | This <a>Lens</a> views the current target of the <a>Zipper</a>.
focus :: IndexedLens' i (Zipper h i a) a

-- | Construct a <a>Zipper</a> that can explore anything, and start it at
--   the <a>Top</a>.
zipper :: a -> Top :>> a

-- | Return the index of the focus.
focalPoint :: Zipper h i a -> i

-- | Return the index into the current <a>Traversal</a> within the current
--   level of the <a>Zipper</a>.
--   
--   <pre>
--   <a>jerkTo</a> (<a>tooth</a> l) l = <a>Just</a>
--   </pre>
--   
--   Mnemonically, zippers have a number of <a>teeth</a> within each level.
--   This is which <a>tooth</a> you are currently at.
--   
--   This is based on ordinal position regardless of the underlying index
--   type. It may be excessively expensive for a list.
--   
--   <a>focalPoint</a> may be much cheaper if you have a <a>Traversal</a>
--   indexed by ordinal position!
tooth :: Zipper h i a -> Int

-- | Move the <a>Zipper</a> <a>upward</a>, closing the current level and
--   focusing on the parent element.
--   
--   NB: Attempts to move upward from the <a>Top</a> of the <a>Zipper</a>
--   will fail to typecheck.
upward :: Ord j => (h :> (s :@ j)) :> (a :@ i) -> h :> (s :@ j)

-- | Jerk the <a>Zipper</a> one <a>tooth</a> to the <a>rightward</a> within
--   the current <a>Lens</a> or <a>Traversal</a>.
--   
--   Attempts to move past the start of the current <a>Traversal</a> (or
--   trivially, the current <a>Lens</a>) will return <a>mzero</a>.
--   
--   <pre>
--   &gt;&gt;&gt; isNothing $ zipper "hello" &amp; rightward
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper "hello" &amp; fromWithin traverse &amp; rightward &lt;&amp;&gt; view focus
--   'e'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper "hello" &amp; fromWithin traverse &amp; rightward &lt;&amp;&gt; focus .~ 'u' &lt;&amp;&gt; rezip
--   "hullo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper (1,2) &amp; fromWithin both &amp; tug rightward &amp; focus .~ 3
--   (1,3)
--   </pre>
rightward :: MonadPlus m => h :> (a :@ i) -> m (h :> (a :@ i))

-- | Jerk the <a>Zipper</a> <a>leftward</a> one <a>tooth</a> within the
--   current <a>Lens</a> or <a>Traversal</a>.
--   
--   Attempts to move past the end of the current <a>Traversal</a> (or
--   trivially, the current <a>Lens</a>) will return <a>mzero</a>.
--   
--   <pre>
--   &gt;&gt;&gt; isNothing $ zipper "hello" &amp; leftward
--   True
--   </pre>
leftward :: MonadPlus m => h :> (a :@ i) -> m (h :> (a :@ i))

-- | Move to the leftmost position of the current <a>Traversal</a>.
--   
--   This is just a convenient alias for <tt><a>farthest</a>
--   <a>leftward</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; zipper "hello" &amp; fromWithin traverse &amp; leftmost &amp; focus .~ 'a' &amp; rezip
--   "aello"
--   </pre>
leftmost :: a :> (b :@ i) -> a :> (b :@ i)

-- | Move to the rightmost position of the current <a>Traversal</a>.
--   
--   This is just a convenient alias for <tt><a>farthest</a>
--   <a>rightward</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; zipper "hello" &amp; fromWithin traverse &amp; rightmost &amp; focus .~ 'y' &amp; leftmost &amp; focus .~ 'j' &amp; rezip
--   "jelly"
--   </pre>
rightmost :: a :> (b :@ i) -> a :> (b :@ i)

-- | This allows you to safely <a>tug</a> <a>leftward</a> or <a>tug</a>
--   <a>rightward</a> on a <a>Zipper</a>. This will attempt the move, and
--   stay where it was if it fails.
--   
--   The more general signature allows its use in other circumstances,
--   however.
--   
--   <pre>
--   <a>tug</a> f x ≡ <a>fromMaybe</a> a (f a)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper "hello" &amp; within traverse &lt;&amp;&gt; tug leftward &lt;&amp;&gt; focus .~ 'j'
--   "jello"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper "hello" &amp; within traverse &lt;&amp;&gt; tug rightward &lt;&amp;&gt; focus .~ 'u'
--   "hullo"
--   </pre>
tug :: (a -> Maybe a) -> a -> a

-- | This allows you to safely <tt><a>tug</a> <a>leftward</a></tt> or
--   <tt><a>tug</a> <a>rightward</a></tt> multiple times on a
--   <a>Zipper</a>, moving multiple steps in a given direction and stopping
--   at the last place you couldn't move from. This lets you safely move a
--   <a>Zipper</a>, because it will stop at either end.
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper "stale" &amp; within traverse &lt;&amp;&gt; tugs rightward 2 &lt;&amp;&gt; focus .~ 'y'
--   "style"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper "want" &amp; fromWithin traverse &amp; tugs rightward 2 &amp; focus .~ 'r' &amp; tugs leftward 100 &amp; focus .~ 'c'
--   "cart"
--   </pre>
tugs :: (a -> Maybe a) -> Int -> a -> a

-- | Move in a direction as far as you can go, then stop there.
--   
--   This repeatedly applies a function until it returns <a>Nothing</a>,
--   and then returns the last answer.
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper ("hello","world") &amp; downward _1 &amp; within traverse &lt;&amp;&gt; rightmost &lt;&amp;&gt; focus .~ 'a'
--   ("hella","world")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper ("hello","there") &amp; fromWithin (both.traverse) &amp; rightmost &amp; focus .~ 'm'
--   ("hello","therm")
--   </pre>
farthest :: (a -> Maybe a) -> a -> a

-- | This allows for you to repeatedly pull a <a>Zipper</a> in a given
--   direction, failing if it falls off the end.
--   
--   <pre>
--   &gt;&gt;&gt; isNothing $ zipper "hello" &amp; within traverse &gt;&gt;= jerks rightward 10
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper "silly" &amp; within traverse &gt;&gt;= jerks rightward 3 &lt;&amp;&gt; focus .~ 'k'
--   "silky"
--   </pre>
jerks :: Monad m => (a -> m a) -> Int -> a -> m a

-- | Returns the number of siblings at the current level in the
--   <a>Zipper</a>.
--   
--   <pre>
--   <a>teeth</a> z <a>&gt;=</a> 1
--   </pre>
--   
--   <i>NB:</i> If the current <a>Traversal</a> targets an infinite number
--   of elements then this may not terminate.
--   
--   This is also a particularly expensive operation to perform on an
--   unbalanced tree.
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; teeth
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; fromWithin both &amp; teeth
--   2
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; downward _1 &amp; teeth
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; downward _1 &amp; fromWithin traverse &amp; teeth
--   5
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; fromWithin (_1.traverse) &amp; teeth
--   5
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; fromWithin (both.traverse) &amp; teeth
--   10
--   </pre>
teeth :: h :> (a :@ i) -> Int

-- | Move the <a>Zipper</a> horizontally to the element in the <tt>n</tt>th
--   position in the current level, absolutely indexed, starting with the
--   <a>farthest</a> <a>leftward</a> as <tt>0</tt>.
--   
--   This returns <a>mzero</a> if the target element doesn't exist.
--   
--   <pre>
--   <a>jerkTo</a> n ≡ <a>jerks</a> <a>rightward</a> n <a>.</a> <a>farthest</a> <a>leftward</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isNothing $ zipper "not working." &amp; jerkTo 20
--   True
--   </pre>
jerkTo :: MonadPlus m => Int -> (h :> (a :@ i)) -> m (h :> (a :@ i))

-- | Move the <a>Zipper</a> horizontally to the element in the <tt>n</tt>th
--   position of the current level, absolutely indexed, starting with the
--   <a>farthest</a> <a>leftward</a> as <tt>0</tt>.
--   
--   If the element at that position doesn't exist, then this will clamp to
--   the range <tt>0 <a>&lt;=</a> n <a>&lt;</a> <a>teeth</a></tt>.
--   
--   <pre>
--   <a>tugTo</a> n ≡ <a>tugs</a> <a>rightward</a> n <a>.</a> <a>farthest</a> <a>leftward</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper "not working." &amp; fromWithin traverse &amp; tugTo 100 &amp; focus .~ '!' &amp; tugTo 1 &amp; focus .~ 'u'
--   "nut working!"
--   </pre>
tugTo :: Int -> h :> (a :@ i) -> h :> (a :@ i)

-- | Move towards a particular index in the current <a>Traversal</a>.
moveToward :: i -> h :> (a :@ i) -> h :> (a :@ i)

-- | Move horizontally to a particular index <tt>i</tt> in the current
--   <a>Traversal</a>. In the case of simple zippers, the index is
--   <a>Int</a> and we can move between traversals fairly easily:
--   
--   <pre>
--   &gt;&gt;&gt; zipper (42, 32) &amp; fromWithin both &amp; moveTo 0 &lt;&amp;&gt; view focus
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper (42, 32) &amp; fromWithin both &amp; moveTo 1 &lt;&amp;&gt; view focus
--   32
--   </pre>
moveTo :: MonadPlus m => i -> h :> (a :@ i) -> m (h :> (a :@ i))

-- | Construct an <a>IndexedLens</a> from <a>ALens</a> where the index is
--   fixed to <tt>0</tt>.
lensed :: ALens' s a -> IndexedLens' Int s a

-- | Step down into a <a>Lens</a>. This is a constrained form of
--   <a>fromWithin</a> for when you know there is precisely one target that
--   can never fail.
--   
--   <pre>
--   <a>downward</a> :: <a>Lens'</a> s a -&gt; (h <a>:&gt;</a> s) -&gt; h <a>:&gt;</a> s <a>:&gt;</a> a
--   <a>downward</a> :: <a>Iso'</a> s a  -&gt; (h <a>:&gt;</a> s) -&gt; h <a>:&gt;</a> s <a>:&gt;</a> a
--   </pre>
downward :: forall j h s a. ALens' s a -> h :> (s :@ j) -> (h :> (s :@ j)) :>> a

-- | Step down into a <a>IndexedLens</a>. This is a constrained form of
--   <a>ifromWithin</a> for when you know there is precisely one target
--   that can never fail.
--   
--   <pre>
--   <a>idownward</a> :: <a>IndexedLens'</a> i s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i
--   </pre>
idownward :: forall i j h s a. Ord i => AnIndexedLens' i s a -> h :> (s :@ j) -> (h :> (s :@ j)) :> (a :@ i)

-- | Step down into the <a>leftmost</a> entry of a <a>Traversal</a>.
--   
--   <pre>
--   <a>within</a> :: <a>Traversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   <a>within</a> :: <a>Prism'</a> s a     -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   <a>within</a> :: <a>Lens'</a> s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   <a>within</a> :: <a>Iso'</a> s a       -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   </pre>
--   
--   <pre>
--   <a>within</a> :: <a>MonadPlus</a> m =&gt; <a>ATraversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; m (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   </pre>
within :: MonadPlus m => LensLike' (Indexing (Bazaar' (Indexed Int) a)) s a -> (h :> (s :@ j)) -> m ((h :> (s :@ j)) :>> a)

-- | Step down into the <a>leftmost</a> entry of an
--   <a>IndexedTraversal</a>.
--   
--   <i>Note:</i> The index is assumed to be ordered and must increase
--   monotonically or else you cannot (safely) <a>moveTo</a> or
--   <a>moveToward</a> or use tapes.
--   
--   <pre>
--   <a>iwithin</a> :: <a>IndexedTraversal'</a> i s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i)
--   <a>iwithin</a> :: <a>IndexedLens'</a> i s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i)
--   </pre>
--   
--   <pre>
--   <a>iwithin</a> :: <a>MonadPlus</a> m =&gt; <a>ATraversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; m (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   </pre>
iwithin :: (MonadPlus m, Ord i) => AnIndexedTraversal' i s a -> (h :> (s :@ j)) -> m ((h :> (s :@ j)) :> (a :@ i))

-- | Step down into every entry of a <a>Traversal</a> simultaneously.
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; withins both &gt;&gt;= leftward &gt;&gt;= withins traverse &gt;&gt;= rightward &lt;&amp;&gt; focus %~ toUpper &lt;&amp;&gt; rezip :: [(String,String)]
--   [("hEllo","world"),("heLlo","world"),("helLo","world"),("hellO","world")]
--   </pre>
--   
--   <pre>
--   <a>withins</a> :: <a>Traversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a]
--   <a>withins</a> :: <a>Lens'</a> s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a]
--   <a>withins</a> :: <a>Iso'</a> s a       -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a]
--   </pre>
withins :: MonadPlus m => LensLike' (Indexing (Bazaar' (Indexed Int) a)) s a -> (h :> (s :@ j)) -> m ((h :> (s :@ j)) :>> a)

-- | Step down into every entry of an <a>IndexedTraversal</a>
--   simultaneously.
--   
--   <i>Note:</i> The index is assumed to be ordered and must increase
--   monotonically or else you cannot (safely) <a>moveTo</a> or
--   <a>moveToward</a> or use tapes.
--   
--   <pre>
--   <a>iwithins</a> :: <a>IndexedTraversal'</a> i s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i]
--   <a>iwithins</a> :: <a>IndexedLens'</a> i s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i]
--   </pre>
iwithins :: (MonadPlus m, Ord i) => AnIndexedTraversal' i s a -> (h :> (s :@ j)) -> m ((h :> (s :@ j)) :> (a :@ i))

-- | Unsafely step down into a <a>Traversal</a> that is <i>assumed</i> to
--   be non-empty.
--   
--   If this invariant is not met then this will usually result in an
--   error!
--   
--   <pre>
--   <a>fromWithin</a> :: <a>Traversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a
--   <a>fromWithin</a> :: <a>Lens'</a> s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a
--   <a>fromWithin</a> :: <a>Iso'</a> s a       -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a
--   </pre>
--   
--   You can reason about this function as if the definition was:
--   
--   <pre>
--   <a>fromWithin</a> l ≡ <a>fromJust</a> <a>.</a> <a>within</a> l
--   </pre>
fromWithin :: LensLike' (Indexing (Bazaar' (Indexed Int) a)) s a -> (h :> (s :@ j)) -> (h :> (s :@ j)) :>> a

-- | Unsafey step down into an <a>IndexedTraversal</a> that is
--   <i>assumed</i> to be non-empty
--   
--   If this invariant is not met then this will usually result in an
--   error!
--   
--   <pre>
--   <a>ifromWithin</a> :: <a>IndexedTraversal'</a> i s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i
--   <a>ifromWithin</a> :: <a>IndexedLens'</a> i s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i
--   </pre>
--   
--   You can reason about this function as if the definition was:
--   
--   <pre>
--   <a>fromWithin</a> l ≡ <a>fromJust</a> <a>.</a> <a>within</a> l
--   </pre>
ifromWithin :: Ord i => AnIndexedTraversal' i s a -> (h :> (s :@ j)) -> (h :> (s :@ j)) :> (a :@ i)

-- | This enables us to pull the <a>Zipper</a> back up to the <a>Top</a>.
class Zipping h a
recoil :: Zipping h a => Coil h i a -> Jacket i a -> Zipped h a

-- | Close something back up that you opened as a <a>Zipper</a>.
rezip :: Zipping h a => (h :> (a :@ i)) -> Zipped h a

-- | Extract the current <a>focus</a> from a <a>Zipper</a> as a
--   <a>Pretext</a>, with access to the current index.
focusedContext :: (Indexable i p, Zipping h a) => (h :> (a :@ i)) -> Pretext p a a (Zipped h a)

-- | A <a>Tape</a> is a recorded path through the (indexed)
--   <a>Traversal</a> chain of a <a>Zipper</a>.
data Tape h i a
[Tape] :: Track h i a -> i -> Tape h i a

-- | Save the current path as as a <a>Tape</a> we can play back later.
saveTape :: Zipper h i a -> Tape h i a

-- | Restore ourselves to a previously recorded position precisely.
--   
--   If the position does not exist, then fail.
restoreTape :: MonadPlus m => Tape h i a -> Zipped h a -> m (Zipper h i a)

-- | Restore ourselves to a location near our previously recorded position.
--   
--   When moving left to right through a <a>Traversal</a>, if this will
--   clamp at each level to the range <tt>0 <a>&lt;=</a> k <a>&lt;</a>
--   <a>teeth</a></tt>, so the only failures will occur when one of the
--   sequence of downward traversals find no targets.
restoreNearTape :: MonadPlus m => Tape h i a -> Zipped h a -> m (Zipper h i a)

-- | Restore ourselves to a previously recorded position.
--   
--   This *assumes* that nothing has been done in the meantime to affect
--   the existence of anything on the entire path.
--   
--   Motions <a>leftward</a> or <a>rightward</a> are clamped, but all
--   traversals included on the <a>Tape</a> are assumed to be non-empty.
--   
--   Violate these assumptions at your own risk!
unsafelyRestoreTape :: Tape h i a -> Zipped h a -> Zipper h i a

-- | This is used to peel off the path information from a <a>Coil</a> for
--   use when saving the current path for later replay.
peel :: Coil h i a -> Track h i a

-- | The <a>Track</a> forms the bulk of a <a>Tape</a>.
data Track t i a
[Track] :: Track Top Int a
[Fork] :: Ord i => Track h j s -> j -> AnIndexedTraversal' i s a -> Track (Zipper h j s) i a

-- | Restore ourselves to a previously recorded position precisely.
--   
--   If the position does not exist, then fail.
restoreTrack :: MonadPlus m => Track h i a -> Zipped h a -> m (Zipper h i a)

-- | Restore ourselves to a location near our previously recorded position.
--   
--   When moving <a>leftward</a> to <a>rightward</a> through a
--   <a>Traversal</a>, if this will clamp at each level to the range <tt>0
--   <a>&lt;=</a> k <a>&lt;</a> <a>teeth</a></tt>, so the only failures
--   will occur when one of the sequence of downward traversals find no
--   targets.
restoreNearTrack :: MonadPlus m => Track h i a -> Zipped h a -> m (Zipper h i a)

-- | Restore ourselves to a previously recorded position.
--   
--   This *assumes* that nothing has been done in the meantime to affect
--   the existence of anything on the entire <a>Path</a>.
--   
--   Motions <a>leftward</a> or <a>rightward</a> are clamped, but all
--   traversals included on the <a>Tape</a> are assumed to be non-empty.
--   
--   Violate these assumptions at your own risk!
unsafelyRestoreTrack :: Track h i a -> Zipped h a -> Zipper h i a
instance (GHC.Show.Show a, GHC.Show.Show i) => GHC.Show.Show (Control.Zipper.Internal.Path i a)
instance (GHC.Show.Show a, GHC.Show.Show i) => GHC.Show.Show (Control.Zipper.Internal.Jacket i a)
instance Control.Zipper.Internal.Zipping Control.Zipper.Internal.Top a
instance Control.Zipper.Internal.Zipping h s => Control.Zipper.Internal.Zipping (Control.Zipper.Internal.Zipper h i s) a
instance GHC.Base.Functor (Control.Zipper.Internal.Path i)
instance GHC.Base.Functor (Control.Zipper.Internal.Flow i b)
instance Data.Functor.Bind.Class.Apply (Control.Zipper.Internal.Flow i b)
instance GHC.Base.Applicative (Control.Zipper.Internal.Flow i b)
instance GHC.Base.Functor (Control.Zipper.Internal.Jacket i)
instance Data.Foldable.Foldable (Control.Zipper.Internal.Jacket i)
instance Data.Traversable.Traversable (Control.Zipper.Internal.Jacket i)
instance Control.Lens.Indexed.FunctorWithIndex i (Control.Zipper.Internal.Jacket i)
instance Control.Lens.Indexed.FoldableWithIndex i (Control.Zipper.Internal.Jacket i)
instance Control.Lens.Indexed.TraversableWithIndex i (Control.Zipper.Internal.Jacket i)
instance Data.Semigroup.Semigroup (Control.Zipper.Internal.Jacket i a)
instance GHC.Base.Monoid (Control.Zipper.Internal.Jacket i a)


-- | This module provides a <a>Zipper</a> with fairly strong type checking
--   guarantees.
--   
--   The code here is inspired by Brandon Simmons' <tt>zippo</tt> package,
--   but uses a different approach to represent the <a>Zipper</a> that
--   makes the whole thing look like his breadcrumb trail, and can move
--   side-to-side through traversals.
--   
--   Some examples types:
--   
--   <ul>
--   <li><i><tt><a>Top</a> <a>:&gt;&gt;</a> a</tt></i> represents a trivial
--   <a>Zipper</a> with its focus at the root.</li>
--   <li><i><tt><a>Top</a> <a>:&gt;&gt;</a> <a>Tree</a> a <a>:&gt;&gt;</a>
--   a</tt></i> represents a <a>Zipper</a> that starts with a <a>Tree</a>
--   and descends in a single step to values of type <tt>a</tt>.</li>
--   <li><i><tt><a>Top</a> <a>:&gt;&gt;</a> <a>Tree</a> a <a>:&gt;&gt;</a>
--   <a>Tree</a> a <a>:&gt;&gt;</a> <a>Tree</a> a</tt></i> represents a
--   <a>Zipper</a> into a <a>Tree</a> with an intermediate bookmarked
--   <a>Tree</a>, focusing in yet another <a>Tree</a>.</li>
--   </ul>
--   
--   Since individual levels of a <a>Zipper</a> are managed by an arbitrary
--   <a>IndexedTraversal</a>, you can move left and right through the
--   <a>IndexedTraversal</a> selecting neighboring elements.
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; downward _1 &amp; fromWithin traverse &amp; focus .~ 'J' &amp; rightmost &amp; focus .~ 'y' &amp; rezip
--   ("Jelly","world")
--   </pre>
--   
--   This is particularly powerful when compiled with <a>plate</a>,
--   <a>uniplate</a> or <a>biplate</a> 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 <a>moveTo</a>. When used with traversals for balanced tree-like
--   structures such as an <a>IntMap</a> or <a>Map</a>, searching for a key
--   with <a>moveTo</a> can be done in logarithmic time.
module Control.Zipper

-- | This is used to represent the <a>Top</a> of the <a>Zipper</a>.
--   
--   Every <a>Zipper</a> starts with <a>Top</a>.
--   
--   <i>e.g.</i> <tt><a>Top</a> <a>:&gt;&gt;</a> a</tt> is the type of the
--   trivial <a>Zipper</a>.
data Top

-- | This type family represents a <a>Zipper</a> with the <tt>p</tt>
--   variable abstracting over the position and the index, in terms of
--   <a>:@</a>. You can visually see it in type signatures as:
--   
--   <pre>
--   h <a>:&gt;</a> (a <a>:@</a> i) = <a>Zipper</a> h i a
--   </pre>

-- | Many zippers are indexed by Int keys. This type alias is convenient
--   for reducing syntactic noise for talking about these boring indices.
type h :>> a = Zipper h Int a

-- | An empty data type, used to represent the pairing of a position in a
--   <a>Zipper</a> with an index. See <a>:&gt;</a>.
data (:@) a i

-- | This is the type of a <a>Zipper</a>. It visually resembles a
--   "breadcrumb trail" as used in website navigation. Each breadcrumb in
--   the trail represents a level you can move up to.
--   
--   This type operator associates to the left, so you can use a type like
--   
--   <pre>
--   <a>Top</a> <a>:&gt;&gt;</a> (<a>String</a>,<a>Double</a>) <a>:&gt;&gt;</a> <a>String</a> <a>:&gt;&gt;</a> <a>Char</a>
--   </pre>
--   
--   to represent a <a>Zipper</a> from
--   <tt>(<a>String</a>,<a>Double</a>)</tt> down to <a>Char</a> that has an
--   intermediate crumb for the <a>String</a> containing the <a>Char</a>.
--   
--   You can construct a <a>Zipper</a> into *any* data structure with
--   <a>zipper</a>.
--   
--   You can repackage up the contents of a <a>Zipper</a> with
--   <a>rezip</a>.
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper 42
--   42
--   </pre>
--   
--   The combinators in this module provide lot of things you can do to the
--   <a>Zipper</a> while you have it open.
--   
--   Note that a value of type <tt>h <a>:&gt;</a> s <a>:&gt;</a> a</tt>
--   doesn't actually contain a value of type <tt>h <a>:&gt;</a> s</tt> --
--   as we descend into a level, the previous level is unpacked and stored
--   in <a>Coil</a> form. Only one value of type <tt>_ <a>:&gt;</a> _</tt>
--   exists at any particular time for any particular <a>Zipper</a>.
data Zipper h i a

-- | Construct a <a>Zipper</a> that can explore anything, and start it at
--   the <a>Top</a>.
zipper :: a -> Top :>> a

-- | This <a>Lens</a> views the current target of the <a>Zipper</a>.
focus :: IndexedLens' i (Zipper h i a) a

-- | Extract the current <a>focus</a> from a <a>Zipper</a> as a
--   <a>Pretext</a>, with access to the current index.
focusedContext :: (Indexable i p, Zipping h a) => (h :> (a :@ i)) -> Pretext p a a (Zipped h a)

-- | Move the <a>Zipper</a> <a>upward</a>, closing the current level and
--   focusing on the parent element.
--   
--   NB: Attempts to move upward from the <a>Top</a> of the <a>Zipper</a>
--   will fail to typecheck.
upward :: Ord j => (h :> (s :@ j)) :> (a :@ i) -> h :> (s :@ j)

-- | Step down into a <a>Lens</a>. This is a constrained form of
--   <a>fromWithin</a> for when you know there is precisely one target that
--   can never fail.
--   
--   <pre>
--   <a>downward</a> :: <a>Lens'</a> s a -&gt; (h <a>:&gt;</a> s) -&gt; h <a>:&gt;</a> s <a>:&gt;</a> a
--   <a>downward</a> :: <a>Iso'</a> s a  -&gt; (h <a>:&gt;</a> s) -&gt; h <a>:&gt;</a> s <a>:&gt;</a> a
--   </pre>
downward :: forall j h s a. ALens' s a -> h :> (s :@ j) -> (h :> (s :@ j)) :>> a

-- | Step down into a <a>IndexedLens</a>. This is a constrained form of
--   <a>ifromWithin</a> for when you know there is precisely one target
--   that can never fail.
--   
--   <pre>
--   <a>idownward</a> :: <a>IndexedLens'</a> i s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i
--   </pre>
idownward :: forall i j h s a. Ord i => AnIndexedLens' i s a -> h :> (s :@ j) -> (h :> (s :@ j)) :> (a :@ i)

-- | Step down into the <a>leftmost</a> entry of a <a>Traversal</a>.
--   
--   <pre>
--   <a>within</a> :: <a>Traversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   <a>within</a> :: <a>Prism'</a> s a     -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   <a>within</a> :: <a>Lens'</a> s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   <a>within</a> :: <a>Iso'</a> s a       -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   </pre>
--   
--   <pre>
--   <a>within</a> :: <a>MonadPlus</a> m =&gt; <a>ATraversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; m (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   </pre>
within :: MonadPlus m => LensLike' (Indexing (Bazaar' (Indexed Int) a)) s a -> (h :> (s :@ j)) -> m ((h :> (s :@ j)) :>> a)

-- | Step down into the <a>leftmost</a> entry of an
--   <a>IndexedTraversal</a>.
--   
--   <i>Note:</i> The index is assumed to be ordered and must increase
--   monotonically or else you cannot (safely) <a>moveTo</a> or
--   <a>moveToward</a> or use tapes.
--   
--   <pre>
--   <a>iwithin</a> :: <a>IndexedTraversal'</a> i s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i)
--   <a>iwithin</a> :: <a>IndexedLens'</a> i s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; <a>Maybe</a> (h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i)
--   </pre>
--   
--   <pre>
--   <a>iwithin</a> :: <a>MonadPlus</a> m =&gt; <a>ATraversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; m (h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a)
--   </pre>
iwithin :: (MonadPlus m, Ord i) => AnIndexedTraversal' i s a -> (h :> (s :@ j)) -> m ((h :> (s :@ j)) :> (a :@ i))

-- | Step down into every entry of a <a>Traversal</a> simultaneously.
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; withins both &gt;&gt;= leftward &gt;&gt;= withins traverse &gt;&gt;= rightward &lt;&amp;&gt; focus %~ toUpper &lt;&amp;&gt; rezip :: [(String,String)]
--   [("hEllo","world"),("heLlo","world"),("helLo","world"),("hellO","world")]
--   </pre>
--   
--   <pre>
--   <a>withins</a> :: <a>Traversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a]
--   <a>withins</a> :: <a>Lens'</a> s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a]
--   <a>withins</a> :: <a>Iso'</a> s a       -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a]
--   </pre>
withins :: MonadPlus m => LensLike' (Indexing (Bazaar' (Indexed Int) a)) s a -> (h :> (s :@ j)) -> m ((h :> (s :@ j)) :>> a)

-- | Step down into every entry of an <a>IndexedTraversal</a>
--   simultaneously.
--   
--   <i>Note:</i> The index is assumed to be ordered and must increase
--   monotonically or else you cannot (safely) <a>moveTo</a> or
--   <a>moveToward</a> or use tapes.
--   
--   <pre>
--   <a>iwithins</a> :: <a>IndexedTraversal'</a> i s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i]
--   <a>iwithins</a> :: <a>IndexedLens'</a> i s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; [h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i]
--   </pre>
iwithins :: (MonadPlus m, Ord i) => AnIndexedTraversal' i s a -> (h :> (s :@ j)) -> m ((h :> (s :@ j)) :> (a :@ i))

-- | Jerk the <a>Zipper</a> <a>leftward</a> one <a>tooth</a> within the
--   current <a>Lens</a> or <a>Traversal</a>.
--   
--   Attempts to move past the end of the current <a>Traversal</a> (or
--   trivially, the current <a>Lens</a>) will return <a>mzero</a>.
--   
--   <pre>
--   &gt;&gt;&gt; isNothing $ zipper "hello" &amp; leftward
--   True
--   </pre>
leftward :: MonadPlus m => h :> (a :@ i) -> m (h :> (a :@ i))

-- | Jerk the <a>Zipper</a> one <a>tooth</a> to the <a>rightward</a> within
--   the current <a>Lens</a> or <a>Traversal</a>.
--   
--   Attempts to move past the start of the current <a>Traversal</a> (or
--   trivially, the current <a>Lens</a>) will return <a>mzero</a>.
--   
--   <pre>
--   &gt;&gt;&gt; isNothing $ zipper "hello" &amp; rightward
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper "hello" &amp; fromWithin traverse &amp; rightward &lt;&amp;&gt; view focus
--   'e'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper "hello" &amp; fromWithin traverse &amp; rightward &lt;&amp;&gt; focus .~ 'u' &lt;&amp;&gt; rezip
--   "hullo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper (1,2) &amp; fromWithin both &amp; tug rightward &amp; focus .~ 3
--   (1,3)
--   </pre>
rightward :: MonadPlus m => h :> (a :@ i) -> m (h :> (a :@ i))

-- | Move to the leftmost position of the current <a>Traversal</a>.
--   
--   This is just a convenient alias for <tt><a>farthest</a>
--   <a>leftward</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; zipper "hello" &amp; fromWithin traverse &amp; leftmost &amp; focus .~ 'a' &amp; rezip
--   "aello"
--   </pre>
leftmost :: a :> (b :@ i) -> a :> (b :@ i)

-- | Move to the rightmost position of the current <a>Traversal</a>.
--   
--   This is just a convenient alias for <tt><a>farthest</a>
--   <a>rightward</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; zipper "hello" &amp; fromWithin traverse &amp; rightmost &amp; focus .~ 'y' &amp; leftmost &amp; focus .~ 'j' &amp; rezip
--   "jelly"
--   </pre>
rightmost :: a :> (b :@ i) -> a :> (b :@ i)

-- | This allows you to safely <a>tug</a> <a>leftward</a> or <a>tug</a>
--   <a>rightward</a> on a <a>Zipper</a>. This will attempt the move, and
--   stay where it was if it fails.
--   
--   The more general signature allows its use in other circumstances,
--   however.
--   
--   <pre>
--   <a>tug</a> f x ≡ <a>fromMaybe</a> a (f a)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper "hello" &amp; within traverse &lt;&amp;&gt; tug leftward &lt;&amp;&gt; focus .~ 'j'
--   "jello"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper "hello" &amp; within traverse &lt;&amp;&gt; tug rightward &lt;&amp;&gt; focus .~ 'u'
--   "hullo"
--   </pre>
tug :: (a -> Maybe a) -> a -> a

-- | This allows you to safely <tt><a>tug</a> <a>leftward</a></tt> or
--   <tt><a>tug</a> <a>rightward</a></tt> multiple times on a
--   <a>Zipper</a>, moving multiple steps in a given direction and stopping
--   at the last place you couldn't move from. This lets you safely move a
--   <a>Zipper</a>, because it will stop at either end.
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper "stale" &amp; within traverse &lt;&amp;&gt; tugs rightward 2 &lt;&amp;&gt; focus .~ 'y'
--   "style"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper "want" &amp; fromWithin traverse &amp; tugs rightward 2 &amp; focus .~ 'r' &amp; tugs leftward 100 &amp; focus .~ 'c'
--   "cart"
--   </pre>
tugs :: (a -> Maybe a) -> Int -> a -> a

-- | This allows for you to repeatedly pull a <a>Zipper</a> in a given
--   direction, failing if it falls off the end.
--   
--   <pre>
--   &gt;&gt;&gt; isNothing $ zipper "hello" &amp; within traverse &gt;&gt;= jerks rightward 10
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper "silly" &amp; within traverse &gt;&gt;= jerks rightward 3 &lt;&amp;&gt; focus .~ 'k'
--   "silky"
--   </pre>
jerks :: Monad m => (a -> m a) -> Int -> a -> m a

-- | Move in a direction as far as you can go, then stop there.
--   
--   This repeatedly applies a function until it returns <a>Nothing</a>,
--   and then returns the last answer.
--   
--   <pre>
--   &gt;&gt;&gt; fmap rezip $ zipper ("hello","world") &amp; downward _1 &amp; within traverse &lt;&amp;&gt; rightmost &lt;&amp;&gt; focus .~ 'a'
--   ("hella","world")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper ("hello","there") &amp; fromWithin (both.traverse) &amp; rightmost &amp; focus .~ 'm'
--   ("hello","therm")
--   </pre>
farthest :: (a -> Maybe a) -> a -> a

-- | Return the index into the current <a>Traversal</a> within the current
--   level of the <a>Zipper</a>.
--   
--   <pre>
--   <a>jerkTo</a> (<a>tooth</a> l) l = <a>Just</a>
--   </pre>
--   
--   Mnemonically, zippers have a number of <a>teeth</a> within each level.
--   This is which <a>tooth</a> you are currently at.
--   
--   This is based on ordinal position regardless of the underlying index
--   type. It may be excessively expensive for a list.
--   
--   <a>focalPoint</a> may be much cheaper if you have a <a>Traversal</a>
--   indexed by ordinal position!
tooth :: Zipper h i a -> Int

-- | Returns the number of siblings at the current level in the
--   <a>Zipper</a>.
--   
--   <pre>
--   <a>teeth</a> z <a>&gt;=</a> 1
--   </pre>
--   
--   <i>NB:</i> If the current <a>Traversal</a> targets an infinite number
--   of elements then this may not terminate.
--   
--   This is also a particularly expensive operation to perform on an
--   unbalanced tree.
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; teeth
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; fromWithin both &amp; teeth
--   2
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; downward _1 &amp; teeth
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; downward _1 &amp; fromWithin traverse &amp; teeth
--   5
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; fromWithin (_1.traverse) &amp; teeth
--   5
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper ("hello","world") &amp; fromWithin (both.traverse) &amp; teeth
--   10
--   </pre>
teeth :: h :> (a :@ i) -> Int

-- | Move the <a>Zipper</a> horizontally to the element in the <tt>n</tt>th
--   position in the current level, absolutely indexed, starting with the
--   <a>farthest</a> <a>leftward</a> as <tt>0</tt>.
--   
--   This returns <a>mzero</a> if the target element doesn't exist.
--   
--   <pre>
--   <a>jerkTo</a> n ≡ <a>jerks</a> <a>rightward</a> n <a>.</a> <a>farthest</a> <a>leftward</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isNothing $ zipper "not working." &amp; jerkTo 20
--   True
--   </pre>
jerkTo :: MonadPlus m => Int -> (h :> (a :@ i)) -> m (h :> (a :@ i))

-- | Move the <a>Zipper</a> horizontally to the element in the <tt>n</tt>th
--   position of the current level, absolutely indexed, starting with the
--   <a>farthest</a> <a>leftward</a> as <tt>0</tt>.
--   
--   If the element at that position doesn't exist, then this will clamp to
--   the range <tt>0 <a>&lt;=</a> n <a>&lt;</a> <a>teeth</a></tt>.
--   
--   <pre>
--   <a>tugTo</a> n ≡ <a>tugs</a> <a>rightward</a> n <a>.</a> <a>farthest</a> <a>leftward</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rezip $ zipper "not working." &amp; fromWithin traverse &amp; tugTo 100 &amp; focus .~ '!' &amp; tugTo 1 &amp; focus .~ 'u'
--   "nut working!"
--   </pre>
tugTo :: Int -> h :> (a :@ i) -> h :> (a :@ i)

-- | Move horizontally to a particular index <tt>i</tt> in the current
--   <a>Traversal</a>. In the case of simple zippers, the index is
--   <a>Int</a> and we can move between traversals fairly easily:
--   
--   <pre>
--   &gt;&gt;&gt; zipper (42, 32) &amp; fromWithin both &amp; moveTo 0 &lt;&amp;&gt; view focus
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; zipper (42, 32) &amp; fromWithin both &amp; moveTo 1 &lt;&amp;&gt; view focus
--   32
--   </pre>
moveTo :: MonadPlus m => i -> h :> (a :@ i) -> m (h :> (a :@ i))

-- | Move towards a particular index in the current <a>Traversal</a>.
moveToward :: i -> h :> (a :@ i) -> h :> (a :@ i)

-- | Close something back up that you opened as a <a>Zipper</a>.
rezip :: Zipping h a => (h :> (a :@ i)) -> Zipped h a

-- | This represents the type a <a>Zipper</a> will have when it is fully
--   <a>Zipped</a> back up.

-- | This enables us to pull the <a>Zipper</a> back up to the <a>Top</a>.
class Zipping h a

-- | A <a>Tape</a> is a recorded path through the (indexed)
--   <a>Traversal</a> chain of a <a>Zipper</a>.
data Tape h i a

-- | Save the current path as as a <a>Tape</a> we can play back later.
saveTape :: Zipper h i a -> Tape h i a

-- | Restore ourselves to a previously recorded position precisely.
--   
--   If the position does not exist, then fail.
restoreTape :: MonadPlus m => Tape h i a -> Zipped h a -> m (Zipper h i a)

-- | Restore ourselves to a location near our previously recorded position.
--   
--   When moving left to right through a <a>Traversal</a>, if this will
--   clamp at each level to the range <tt>0 <a>&lt;=</a> k <a>&lt;</a>
--   <a>teeth</a></tt>, so the only failures will occur when one of the
--   sequence of downward traversals find no targets.
restoreNearTape :: MonadPlus m => Tape h i a -> Zipped h a -> m (Zipper h i a)

-- | Unsafely step down into a <a>Traversal</a> that is <i>assumed</i> to
--   be non-empty.
--   
--   If this invariant is not met then this will usually result in an
--   error!
--   
--   <pre>
--   <a>fromWithin</a> :: <a>Traversal'</a> s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a
--   <a>fromWithin</a> :: <a>Lens'</a> s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a
--   <a>fromWithin</a> :: <a>Iso'</a> s a       -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;&gt;</a> a
--   </pre>
--   
--   You can reason about this function as if the definition was:
--   
--   <pre>
--   <a>fromWithin</a> l ≡ <a>fromJust</a> <a>.</a> <a>within</a> l
--   </pre>
fromWithin :: LensLike' (Indexing (Bazaar' (Indexed Int) a)) s a -> (h :> (s :@ j)) -> (h :> (s :@ j)) :>> a

-- | Unsafey step down into an <a>IndexedTraversal</a> that is
--   <i>assumed</i> to be non-empty
--   
--   If this invariant is not met then this will usually result in an
--   error!
--   
--   <pre>
--   <a>ifromWithin</a> :: <a>IndexedTraversal'</a> i s a -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i
--   <a>ifromWithin</a> :: <a>IndexedLens'</a> i s a      -&gt; (h <a>:&gt;</a> s:@j) -&gt; h <a>:&gt;</a> s:@j <a>:&gt;</a> a:@i
--   </pre>
--   
--   You can reason about this function as if the definition was:
--   
--   <pre>
--   <a>fromWithin</a> l ≡ <a>fromJust</a> <a>.</a> <a>within</a> l
--   </pre>
ifromWithin :: Ord i => AnIndexedTraversal' i s a -> (h :> (s :@ j)) -> (h :> (s :@ j)) :> (a :@ i)

-- | Restore ourselves to a previously recorded position.
--   
--   This *assumes* that nothing has been done in the meantime to affect
--   the existence of anything on the entire path.
--   
--   Motions <a>leftward</a> or <a>rightward</a> are clamped, but all
--   traversals included on the <a>Tape</a> are assumed to be non-empty.
--   
--   Violate these assumptions at your own risk!
unsafelyRestoreTape :: Tape h i a -> Zipped h a -> Zipper h i a
