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


-- | A monad and monad transformer for nondeterministic computations.
--   
--   Nondeterministic computations
@package nondeterminism
@version 1.4

module Control.Monad.Amb

-- | Just for fun. This is McCarthy's <tt>amb</tt> operator and is a
--   synonym for <tt>aMemberOf</tt>.
amb :: [b] -> AmbT r m b

-- | Generate all partitions of a given size of this list.
aPartitionOfSize :: (Eq a, Monad m) => Int -> [a] -> AmbT r m [[a]]

-- | Generate all partitions of this list.
aPartitionOf :: (Eq t, Monad m) => [t] -> AmbT r m [[t]]

-- | Generate all permutations of a list.
aPermutationOf :: [a] -> AmbT r m [a]

-- | Generate all splits of a list.
aSplitOf :: [a] -> AmbT r m ([a], [a])

-- | Generate all numbers between the given bounds, inclusive.
anIntegerBetween :: (Monad m, Num b, Ord b) => b -> b -> AmbT r m b

-- | Generate each subset of any size from the given list.
aSubsetOf :: [AmbT r m a] -> AmbT r m [a]

-- | Generate each element of the given list.
aMemberOf :: [b] -> AmbT r m b

-- | The most basic primitive that everything else is built out of.
--   Generates <tt>True</tt> and <tt>False</tt>.
aBoolean :: AmbT r m Bool

-- | Run a nondeterministic computation and return <tt>True</tt> if any
--   result is <tt>True</tt>, <tt>False</tt> otherwise.
isPossible :: Amb Bool Bool -> Bool

-- | Run a nondeterministic computation and return <tt>True</tt> if any
--   result is <tt>True</tt>, <tt>False</tt> otherwise.
isPossibleT :: (Monad m) => AmbT Bool m Bool -> m Bool

-- | Run a nondeterministic computation and return <tt>True</tt> if all
--   possible results are <tt>True</tt>, <tt>False</tt> otherwise.
isNecessary :: Amb Bool Bool -> Bool

-- | Run a nondeterministic computation and return <tt>True</tt> if all
--   possible results are <tt>True</tt>, <tt>False</tt> otherwise.
isNecessaryT :: (Monad m) => AmbT Bool m Bool -> m Bool

-- | Run a nondeterministic computation and return a list of all results
--   that the computation can produce. Note that this function is not lazy
--   its result.
allValues :: Amb t t -> [t]

-- | Run a nondeterministic computation and return a list of all results
--   that the computation can produce. Note that this function is not lazy
--   its result.
allValuesT :: (Monad m) => AmbT t m t -> m [t]

-- | Run a nondeterministic computation and return a result of that
--   computation.
oneValue :: Amb a a -> a

-- | Run a nondeterministic computation and return a result of that
--   computation.
oneValueT :: (Monad m) => AmbT b m b -> m b

-- | A helper to inject state into the backtracking stack
tell' :: (Monad m) => [r] -> AmbT r m ()

-- | A helper to inject state into the backtracking stack
tellState :: (Monoid s, MonadState s m) => s -> m ()

-- | When the nondeterministic computation backtracks past this state,
--   execute this nondeterministic computation. Generally used to undo side
--   effects.
uponFailure :: AmbT r m a -> AmbT r m ()

-- | Run the nondeterministic computation. This is internal.
runAmbT :: (Monad m) => AmbT t m t -> m (t, [t])

-- | Run the nondeterministic computation. This is internal.
runAmbTI :: (Monad m) => AmbT a m a -> AmbT a m a -> m (a, [a])

-- | call/cc lifted into the nondeterministic monad. This implements the
--   backtracking behaviour which allows Amb to try different code paths
--   and return multiple results.
ambCC :: ((a -> AmbT r m a1) -> AmbT r m a) -> AmbT r m a

-- | A low-level internal function which executes a nondeterministic
--   computation for its nondeterministic side-effects, such as its ability
--   to produce different results.
forEffects :: (Monad m) => ((t, [t]) -> r) -> (t1 -> AmbT t m t) -> AmbT t m t1 -> m r

-- | <tt>AmbT r m a</tt> is a computation whose current value is of type
--   <tt>a</tt> and which will ultimately return a value of type
--   <tt>r</tt>. The same as <tt>ContT</tt>.
data AmbT r m a
AmbT :: StateT (AmbT r m r) (ContT r (StateT [r] m)) a -> AmbT r m a

-- | From left to right:
--   
--   <ul>
--   <li>the computation to run on failure</li>
--   <li>the continuation captured when making nondeterministic
--   choices</li>
--   <li>record keeping of solutions found so far</li>
--   </ul>
[unAmbT] :: AmbT r m a -> StateT (AmbT r m r) (ContT r (StateT [r] m)) a
type AmbT' m a = forall r. AmbT r m a
type Amb r = AmbT r Identity
type Amb' a = AmbT' Identity a
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Amb.AmbT r)
instance GHC.Base.Monad (Control.Monad.Amb.AmbT r m)
instance GHC.Base.MonadPlus (Control.Monad.Amb.AmbT r m)
instance GHC.Base.Functor (Control.Monad.Amb.AmbT r m)
instance GHC.Base.Applicative (Control.Monad.Amb.AmbT r m)
instance GHC.Base.Alternative (Control.Monad.Amb.AmbT r m)
