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


-- | Class of data structures that can be unfolded.
--   
--   Just as there's a Foldable class, there should also be an Unfoldable
--   class.
--   
--   This package provides one. Example unfolds are:
--   
--   <ul>
--   <li>Random values</li>
--   <li>Enumeration of all values (depth-first or breadth-first)</li>
--   <li>Convert from a list</li>
--   </ul>
--   
--   Some examples can be found in the examples directory.
@package unfoldable
@version 0.7


-- | Unfolders provide a way to unfold data structures. They are basically
--   <a>Alternative</a> instances, but the <a>choose</a> method allows the
--   unfolder to do something special for the recursive positions of the
--   data structure.
module Data.Unfolder

-- | Unfolders provide a way to unfold data structures. The methods have
--   default implementations in terms of <a>Alternative</a>, but you can
--   implement <a>choose</a> to act on recursive positions of the data
--   structure, or simply to provide a faster implementation than
--   <a>asum</a>.
class Alternative f => Unfolder f where choose = asum chooseInt n = choose $ map pure [0 .. n - 1]
choose :: Unfolder f => [f x] -> f x
chooseInt :: Unfolder f => Int -> f Int

-- | If an unfolder is monadic, <a>choose</a> can be implemented in terms
--   of <a>chooseInt</a>.
chooseMonadDefault :: (Monad m, Unfolder m) => [m x] -> m x

-- | If a datatype is enumerable, we can use <a>chooseInt</a> to generate a
--   value. This is the function to use if you want to unfold a datatype
--   that has no type arguments (has kind <tt>*</tt>).
between :: (Unfolder f, Enum a) => a -> a -> f a

-- | <a>betweenD</a> uses <a>choose</a> to generate a value. It chooses
--   between the lower bound and one of the higher values. This means that
--   f.e. breadth-first unfolding and arbitrary will prefer lower values.
betweenD :: (Unfolder f, Enum a) => a -> a -> f a

-- | If a datatype is also bounded, we choose between all possible values.
--   
--   <pre>
--   boundedEnum = between minBound maxBound
--   </pre>
boundedEnum :: (Unfolder f, Bounded a, Enum a) => f a

-- | <pre>
--   boundedEnumD = betweenD minBound maxBound
--   </pre>
boundedEnumD :: (Unfolder f, Bounded a, Enum a) => f a
newtype Random g m a
Random :: StateT g m a -> Random g m a
getRandom :: Random g m a -> StateT g m a

-- | A variant of Test.QuickCheck.Gen, with failure and a count of the
--   number of recursive positions.
data Arb a
Arb :: Int -> (StdGen -> Int -> Maybe a) -> Arb a
arbUnit :: Arbitrary a => Arb a

-- | Variant of <a>Constant</a> that does multiplication of the constants
--   for <tt>&lt;*&gt;</tt> and addition for <tt>&lt;|&gt;</tt>.
newtype NumConst a x
NumConst :: a -> NumConst a x
getNumConst :: NumConst a x -> a

-- | An <a>UnfolderTransformer</a> changes the way an <a>Unfolder</a>
--   unfolds.
class UnfolderTransformer t
lift :: (UnfolderTransformer t, Unfolder f) => f a -> t f a

-- | Run an unfolding function with one argument using an
--   <a>UnfolderTransformer</a>, given a way to run the transformer.
ala :: (UnfolderTransformer t, Unfolder f) => (t f b -> f b) -> (t f a -> t f b) -> f a -> f b

-- | Run an unfolding function with two arguments using an
--   <a>UnfolderTransformer</a>, given a way to run the transformer.
ala2 :: (UnfolderTransformer t, Unfolder f) => (t f c -> f c) -> (t f a -> t f b -> t f c) -> f a -> f b -> f c

-- | Run an unfolding function with three arguments using an
--   <a>UnfolderTransformer</a>, given a way to run the transformer.
ala3 :: (UnfolderTransformer t, Unfolder f) => (t f d -> f d) -> (t f a -> t f b -> t f c -> t f d) -> f a -> f b -> f c -> f d

-- | <a>DualA</a> flips the <tt>&lt;|&gt;</tt> operator from
--   <a>Alternative</a>.
newtype DualA f a
DualA :: f a -> DualA f a
getDualA :: DualA f a -> f a

-- | Natural transformations
data NT f g
NT :: (forall a. f a -> g a) -> NT f g
getNT :: NT f g -> forall a. f a -> g a
newtype WithRec f a
WithRec :: ReaderT (Int -> NT f f) f a -> WithRec f a
getWithRec :: WithRec f a -> ReaderT (Int -> NT f f) f a

-- | Apply a certain function of type <tt>f a -&gt; f a</tt> to the result
--   of a <a>choose</a>. The depth is passed as <a>Int</a>, so you can
--   apply a different function at each depth. Because of a
--   <tt>forall</tt>, the function needs to be wrapped in a <a>NT</a>
--   constructor. See <a>limitDepth</a> for an example how to use this
--   function.
withRec :: (Int -> NT f f) -> WithRec f a -> f a

-- | Limit the depth of an unfolding.
limitDepth :: Unfolder f => Int -> WithRec f a -> f a

-- | Return a generator of values of a given depth. Returns <a>Nothing</a>
--   if there are no values of that depth or deeper. The depth is the
--   number of <a>choose</a> calls.
newtype BFS f x
BFS :: ((Int, Split) -> Maybe [f x]) -> BFS f x
getBFS :: BFS f x -> (Int, Split) -> Maybe [f x]
type Split = Int -> [(Int, Int)]

-- | Change the order of unfolding to be breadth-first, by maximum depth of
--   the components.
bfs :: Unfolder f => BFS f x -> f x

-- | Change the order of unfolding to be breadth-first, by the sum of
--   depths of the components.
bfsBySum :: Unfolder f => BFS f x -> f x
instance Functor m => Functor (Random g m)
instance (Monad m, Functor m) => Applicative (Random g m)
instance Monad m => Monad (Random g m)
instance Eq (f a) => Eq (DualA f a)
instance Show (f a) => Show (DualA f a)
instance Functor f => Functor (DualA f)
instance Applicative f => Applicative (DualA f)
instance Functor f => Functor (WithRec f)
instance Applicative f => Applicative (WithRec f)
instance Alternative f => Alternative (WithRec f)
instance Eq a => Eq (NumConst a x)
instance Show a => Show (NumConst a x)
instance Num a => Unfolder (NumConst a)
instance Num a => Alternative (NumConst a)
instance Num a => Applicative (NumConst a)
instance Functor (NumConst a)
instance Unfolder Arb
instance Alternative Arb
instance Applicative Arb
instance Functor Arb
instance UnfolderTransformer BFS
instance Applicative f => Unfolder (BFS f)
instance Applicative f => Alternative (BFS f)
instance Applicative f => Applicative (BFS f)
instance Functor f => Functor (BFS f)
instance UnfolderTransformer WithRec
instance Unfolder f => Unfolder (WithRec f)
instance UnfolderTransformer DualA
instance Unfolder f => Unfolder (DualA f)
instance Alternative f => Alternative (DualA f)
instance (Functor m, Monad m, RandomGen g) => Unfolder (Random g m)
instance (Functor m, Monad m, RandomGen g) => MonadPlus (Random g m)
instance (Functor m, Monad m, RandomGen g) => Alternative (Random g m)
instance (Monoid w, Unfolder m) => Unfolder (WriterT w m)
instance Unfolder m => Unfolder (ReaderT r m)
instance (MonadPlus m, Unfolder m) => Unfolder (StateT s m)
instance (Monoid w, MonadPlus m, Unfolder m) => Unfolder (RWST r w s m)
instance (Functor m, Monad m) => Unfolder (MaybeT m)
instance Applicative f => Unfolder (ListT f)
instance (Functor m, Monad m, Error e) => Unfolder (ErrorT e m)
instance Unfolder f => Unfolder (Lift f)
instance Unfolder f => Unfolder (Backwards f)
instance Unfolder f => Unfolder (Reverse f)
instance (Unfolder p, Applicative q) => Unfolder (Compose p q)
instance (Unfolder p, Unfolder q) => Unfolder (Product p q)
instance Unfolder Maybe
instance Unfolder []
instance (ArrowZero a, ArrowPlus a) => Unfolder (WrappedArrow a b)
instance MonadPlus m => Unfolder (WrappedMonad m)


-- | Class of data structures that can be unfolded.
module Data.Unfoldable

-- | Data structures that can be unfolded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Unfoldable Tree where
--     unfold fa = choose
--       [ pure Empty
--       , Leaf &lt;$&gt; fa
--       , Node &lt;$&gt; unfold fa &lt;*&gt; fa &lt;*&gt; unfold fa
--       ]
--   </pre>
--   
--   i.e. it follows closely the instance for <tt>Traversable</tt>, but
--   instead of matching on an input value, we <a>choose</a> from a list of
--   all cases.
class Unfoldable t
unfold :: (Unfoldable t, Unfolder f) => f a -> f (t a)

-- | Unfold the structure, always using <tt>()</tt> as elements.
unfold_ :: (Unfoldable t, Unfolder f) => f (t ())

-- | Breadth-first unfold, which orders the result by the number of
--   <a>choose</a> calls.
unfoldBF :: (Unfoldable t, Unfolder f) => f a -> f (t a)

-- | Unfold the structure breadth-first, always using <tt>()</tt> as
--   elements.
unfoldBF_ :: (Unfoldable t, Unfolder f) => f (t ())

-- | <tt>unfoldr</tt> builds a data structure from a seed value. It can be
--   specified as:
--   
--   <pre>
--   unfoldr f z == fromList (Data.List.unfoldr f z)
--   </pre>
unfoldr :: Unfoldable t => (b -> Maybe (a, b)) -> b -> Maybe (t a)

-- | Create a data structure using the list as input. This can fail because
--   there might not be a data structure with the same number of element
--   positions as the number of elements in the list.
fromList :: Unfoldable t => [a] -> Maybe (t a)

-- | Always choose the first constructor.
leftMost :: Unfoldable t => Maybe (t ())

-- | Always choose the last constructor.
rightMost :: Unfoldable t => Maybe (t ())

-- | Generate all the values depth-first.
allDepthFirst :: Unfoldable t => [t ()]

-- | Generate all the values upto a given depth, depth-first.
allToDepth :: Unfoldable t => Int -> [t ()]

-- | Generate all the values breadth-first.
allBreadthFirst :: Unfoldable t => [t ()]

-- | Generate a random value, can be used as default instance for
--   <a>Random</a>.
randomDefault :: (Random a, RandomGen g, Unfoldable t) => g -> (t a, g)

-- | Provides a QuickCheck generator, can be used as default instance for
--   <a>Arbitrary</a>.
arbitraryDefault :: (Arbitrary a, Unfoldable t) => Gen (t a)
instance [safe] Unfoldable f => Unfoldable (Reverse f)
instance [safe] (Unfoldable p, Unfoldable q) => Unfoldable (Compose p q)
instance [safe] (Unfoldable p, Unfoldable q) => Unfoldable (Product p q)
instance [safe] (Bounded a, Enum a) => Unfoldable (Constant a)
instance [safe] Unfoldable Identity
instance [safe] (Bounded a, Enum a) => Unfoldable ((,) a)
instance [safe] (Bounded a, Enum a) => Unfoldable (Either a)
instance [safe] Unfoldable Maybe
instance [safe] Unfoldable []


-- | Class of data structures with 2 type arguments that can be unfolded.
module Data.Biunfoldable

-- | Data structures with 2 type arguments (kind <tt>* -&gt; * -&gt;
--   *</tt>) that can be unfolded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a b = Empty | Leaf a | Node (Tree a b) b (Tree a b)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Biunfoldable Tree where
--     biunfold fa fb = choose
--       [ pure Empty
--       , Leaf &lt;$&gt; fa
--       , Node &lt;$&gt; biunfold fa fb &lt;*&gt; fb &lt;*&gt; biunfold fa fb
--       ]
--   </pre>
--   
--   i.e. it follows closely the instance for <tt>Bitraversable</tt>, but
--   instead of matching on an input value, we <a>choose</a> from a list of
--   all cases.
class Biunfoldable t
biunfold :: (Biunfoldable t, Unfolder f) => f a -> f b -> f (t a b)

-- | Unfold the structure, always using <tt>()</tt> as elements.
biunfold_ :: (Biunfoldable t, Unfolder f) => f (t () ())

-- | Breadth-first unfold, which orders the result by the number of
--   <a>choose</a> calls.
biunfoldBF :: (Biunfoldable t, Unfolder f) => f a -> f b -> f (t a b)

-- | Unfold the structure breadth-first, always using <tt>()</tt> as
--   elements.
biunfoldBF_ :: (Biunfoldable t, Unfolder f) => f (t () ())

-- | <tt>biunfoldr</tt> builds a data structure from a seed value.
biunfoldr :: Biunfoldable t => (c -> Maybe (a, c)) -> (c -> Maybe (b, c)) -> c -> Maybe (t a b)

-- | Create a data structure using the lists as input. This can fail
--   because there might not be a data structure with the same number of
--   element positions as the number of elements in the lists.
fromLists :: Biunfoldable t => [a] -> [b] -> Maybe (t a b)

-- | Generate a random value, can be used as default instance for
--   <a>Random</a>.
randomDefault :: (Random a, Random b, RandomGen g, Biunfoldable t) => g -> (t a b, g)

-- | Provides a QuickCheck generator, can be used as default instance for
--   <a>Arbitrary</a>.
arbitraryDefault :: (Arbitrary a, Arbitrary b, Biunfoldable t) => Gen (t a b)
instance [safe] Biunfoldable Constant
instance [safe] Biunfoldable (,)
instance [safe] Biunfoldable Either