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


-- | Monad (and transformer) for deferred-effect pure
--   prompt-response queries
--   
--   Monad (and transformer) for delayed-effect "pure" prompt-and-response
--   queries.
--   
--   Allows you to specify programs that might query a database, talk to
--   stdio, etc., without ever involving IO or opening the door to
--   arbitrary IO. Write a potentially pure computation describing
--   prompting interactions, etc., without having your type actually do any
--   IO or involve itself with IO or any effectful context.
--   
--   Useful as a source of "things from IO", without ever actually
--   involving IO or arbitrary IO itself; only executing a specific subset
--   of IO (or State, etc.) that you yourself, the caller, specifies
--   explicitly. Safer and more meaningful type.
--   
--   For more information and instructions on usage with examples, see
--   <a>the README</a>.
--   
--   Not quite related to the <i>MonadPrompt</i> library.
@package prompt
@version 0.1.1.2


-- | Provides a typeclass for <a>Applicative</a> and <a>Monad</a> types
--   that give you the ability to, at any time, "prompt" with an <tt>a</tt>
--   and get a <tt>b</tt> in response. The power of this instance is that
--   each type gets to define its own way to deliver a response.
--   
--   This library provides instances for <tt>PromptT</tt> from
--   <a>Control.Monad.Prompt</a> and the monad transformers in
--   <i>transformers</i> and <i>mtl</i>. Feel free to create your own
--   instances too.
--   
--   <pre>
--   data Interactive a = Interactive ((String -&gt; String) -&gt; a)
--   
--   -- at any time, ask with a string to get a string
--   instance MonadPrompt String String Interactive where
--       prompt str = Interactive $ f -&gt; f str
--   </pre>
module Control.Monad.Prompt.Class

-- | An <a>Applicative</a> (and possibly <a>Monad</a>) where you can, at
--   any time, "prompt" with an <tt>a</tt> and receive a <tt>b</tt> in
--   response.
--   
--   Instances include <tt>PromptT</tt> and any <i>transformers</i> monad
--   transformer over another <a>MonadPrompt</a>.
class Applicative m => MonadPrompt a b m | m -> a b

-- | <a>Prompt</a> with an <tt>a</tt> for a <tt>b</tt> in the context of
--   the type.
prompt :: MonadPrompt a b m => a -> m b

-- | <a>Prompt</a> with an <tt>a</tt> for a <tt>b</tt> in the context of
--   the type, and apply the given function to receive a <tt>c</tt>.
prompts :: MonadPrompt a b m => (b -> c) -> a -> m c

-- | A version of <a>prompt</a> strict on its prompting value.
prompt' :: MonadPrompt a b m => a -> m b

-- | A version of <a>prompts</a> strict on its prompting value.
prompts' :: MonadPrompt a b m => (b -> c) -> a -> m c
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.Reader.ReaderT r m)
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.Except.ExceptT e m)
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.Error.ErrorT e m)
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m, GHC.Base.Monoid w) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m, GHC.Base.Monoid w) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m, GHC.Base.Monoid w) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m, GHC.Base.Monoid w) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monad m, Control.Monad.Prompt.Class.MonadPrompt a b m) => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Trans.Maybe.MaybeT m)


-- | Provides the <a>PromptT</a> type, which allows you to program
--   computations that can "ask" or "prompt" with values to get values in
--   return. The computation doesn't care about the process of prompting,
--   or how it works, and has nothing to do with the effectful monad where
--   the prompting will eventually take place.
--   
--   For example, sometimes you might want a computation to be able to
--   query or database, or talk with stdio, but you don't want your type to
--   involve arbitrary IO or be over IO, opening the door to a mess of IO.
--   <a>Prompt</a> lets you write programs that can query "something", and
--   then at a later point in time, run it, providing the method of
--   fulfilling each prompt. Write your program independent of IO, or
--   databases, or stdio, etc.; only later "fill in" what it means. You can
--   even run the same <a>Prompt</a> with different ways to fulfill the
--   prompts --- pure, effectful, etc.
--   
--   For usage examples and a more detailed explanation, see <a>the
--   README</a>.
module Control.Monad.Prompt

-- | Prompt type, providing the ability to "prompt" or "query" by
--   presenting/asking with an <tt>a</tt> and receiving a <tt>b</tt>
--   response.
--   
--   <pre>
--   <a>prompt</a> :: a -&gt; (Prompt a b) b
--   </pre>
--   
--   "Ask with an <tt>a</tt>, get a <tt>b</tt>."
--   
--   Has a <a>Monad</a>, <a>Applicative</a>, <a>Functor</a>, etc. instance
--   so it can be sequenced monadically or applicatively, so you can
--   sequence and bind from <a>prompt</a>.
--   
--   Note that we defer the process of specifying <i>how</i> <a>prompt</a>
--   delivers its <tt>b</tt>. It can take place in IO, or in any other
--   effectful setting...but <a>Prompt</a> doesn't care, and it never
--   involves IO or any arbitrary IO itself.
--   
--   Can be "constructed directly" using <a>mkPrompt</a>, but typically
--   using <a>prompt</a> and the <a>Applicative</a>, <a>Monad</a> instances
--   etc. is better.
type Prompt a b = PromptT a b Identity

-- | Run a <tt><a>Prompt</a> a b r</tt> with a given effectful <tt>a -&gt;
--   m b</tt> "prompt response" function, to get the resulting <tt>r</tt>
--   in <tt>m</tt>. Note that the <a>Prompt</a> itself in general has
--   nothing to do with <tt>m</tt>, and cannot execute arbitrary <tt>m</tt>
--   other than that given in the prompt response function.
--   
--   Effectively treats a <tt><a>Prompt</a> a b</tt> as a <tt>forall m.
--   ReaderT (a -&gt; m b) m</tt>
runPromptM :: Monad m => Prompt a b r -> (a -> m b) -> m r

-- | Run a <tt><a>Prompt</a> a b r</tt> with a pure <tt>a -&gt; b</tt>
--   prompt response function. More or less reduces <tt><a>Prompt</a> a
--   b</tt> to a <tt><tt>Reader</tt> (a -&gt; b)</tt>.
runPrompt :: Prompt a b r -> (a -> b) -> r

-- | Run a <tt><a>Prompt</a> String String</tt> in IO by sending the
--   request to stdout and reading the response from stdin.
interactP :: Prompt String String r -> IO r

-- | Like <a>Prompt</a>, but can perform its "pure" computations in the
--   context of a <a>Traversable</a> <tt>t</tt>, to absorb short-circuiting
--   behvaior with <a>Maybe</a> or <a>Either</a>, logging with
--   <tt>Writer</tt>, etc., but this is in general completely unrelated to
--   the effectful monad where the prompting will eventually take place.
--   Specify short-circuiting and logging logic, without worrying about IO
--   or anything relating to the prompting effect.
--   
--   <pre>
--   <a>prompt</a> :: a -&gt; (PromptT a b t) b
--   </pre>
--   
--   Implements several useful typeclasses for working with the underlying
--   <a>Traversable</a> and integrating effects, like <a>Alternative</a>,
--   <a>MonadError</a>, <a>MonadWriter</a>, etc.
--   
--   Constructor is hidden, but a direct constructing function is exported
--   as <tt>mkPrompT</tt> in the rare case it is needed or wanted.
data PromptT a b t r

-- | Run a <tt><a>PromptT</a> a b t r</tt> with a given effectful <tt>a
--   -&gt; m (t b)</tt> "prompt response" function, to get the resulting
--   <tt>r</tt> in <tt>m</tt> and <tt>t</tt>. The "prompt response"
--   function is able to interact with the underlying <a>Traversable</a>
--   <tt>t</tt>.
--   
--   Note that the <a>PromptT</a> in general has nothing to do with the
--   <tt>m</tt>, and cannot execute arbitrary <tt>m</tt> other than that
--   given in the prompt response function.
runPromptTM :: Monad m => PromptT a b t r -> (a -> m (t b)) -> m (t r)

-- | Run a <tt><a>PromptT</a> a b t r</tt> with a given <tt>a -&gt; t
--   b</tt> function, with <a>Traversable</a> <tt>t</tt>. The effects take
--   place in the same context as the underlying context of the
--   <a>PromptT</a>.
runPromptT :: PromptT a b t r -> (a -> t b) -> t r

-- | Run a <tt><a>PromptT</a> String String</tt> in IO by sending the
--   request to stdout and reading the response from stdin.
interactPT :: Applicative t => PromptT String String t r -> IO (t r)

-- | An <a>Applicative</a> (and possibly <a>Monad</a>) where you can, at
--   any time, "prompt" with an <tt>a</tt> and receive a <tt>b</tt> in
--   response.
--   
--   Instances include <tt>PromptT</tt> and any <i>transformers</i> monad
--   transformer over another <a>MonadPrompt</a>.
class Applicative m => MonadPrompt a b m | m -> a b

-- | <a>Prompt</a> with an <tt>a</tt> for a <tt>b</tt> in the context of
--   the type.
prompt :: MonadPrompt a b m => a -> m b

-- | <a>Prompt</a> with an <tt>a</tt> for a <tt>b</tt> in the context of
--   the type, and apply the given function to receive a <tt>c</tt>.
prompts :: MonadPrompt a b m => (b -> c) -> a -> m c

-- | A version of <a>prompt</a> strict on its prompting value.
prompt' :: MonadPrompt a b m => a -> m b

-- | A version of <a>prompts</a> strict on its prompting value.
prompts' :: MonadPrompt a b m => (b -> c) -> a -> m c

-- | Like <a>prompt</a>, but specialized to <a>PromptT</a> and without the
--   <a>Applicative</a> constraint.
promptP :: a -> PromptT a b t b

-- | Like <a>prompts</a>, but specialized to <a>PromptT</a> and downgrading
--   the <a>Applicative</a> constraint to a <a>Functor</a> constraint.
promptsP :: Functor t => (b -> c) -> a -> PromptT a b t c

-- | Like <a>prompt'</a>, but specialized to <a>PromptT</a> and without the
--   <a>Applicative</a> constraint. Is a <a>promptP</a> strict on its
--   argument.
promptP' :: a -> PromptT a b t b

-- | Like <a>prompts'</a>, but specialized to <a>PromptT</a> and
--   downgrading the <a>Applicative</a> constraint to a <a>Functor</a>
--   constraint. Is a <a>promptsP</a> strict on its argument.
promptsP' :: Functor t => (b -> c) -> a -> PromptT a b t c

-- | Maps the underying <tt>t a</tt> returned by <a>PromptT</a>. Cannot
--   change <tt>t</tt>.
mapPromptT :: (t r -> t s) -> PromptT a b t r -> PromptT a b t s

-- | Swap out the <a>Traversable</a> <tt>t</tt> with a pair of natural
--   transformations. The first maps the output <tt>t a</tt>, and the
--   second maps the result of the prompting function.
hoistP :: (forall s. t s -> u s) -> (forall s. u s -> t s) -> PromptT a b t r -> PromptT a b u r

-- | Like <a>lift</a>, but without the <a>Monad</a> constraint.
liftP :: t r -> PromptT a b t r

-- | Directly construct a <a>PromptT</a>. Has to be able to take a <tt>(a -
--   m (t b)) -&gt; m (t r)</tt> that can work on <i>any</i> <a>Monad</a>.
--   
--   Typically this won't be used, but is provided for completion; using
--   <a>prompt</a> and its <a>Applicative</a>, <a>Monad</a> instances,
--   etc., is more clear.
--   
--   <pre>
--   <a>prompt</a> r = <a>mkPromptT</a> $ g -&gt; g r
--   </pre>
mkPromptT :: (forall m. Monad m => (a -> m (t b)) -> m (t r)) -> PromptT a b t r

-- | Directly construct a <a>Prompt</a>. Has to be able to take a <tt>(a
--   -&gt; m b) -&gt; m r</tt> that can work on <i>any</i> <a>Monad</a>.
--   
--   Typically this won't be used, but is provided for completion; using
--   <a>prompt</a> and its <a>Applicative</a>, <a>Monad</a> instances,
--   etc., is more clear.
mkPrompt :: (forall m. Monad m => (a -> m b) -> m r) -> Prompt a b r
instance GHC.Base.Functor t => GHC.Base.Functor (Control.Monad.Prompt.PromptT a b t)
instance GHC.Base.Applicative t => GHC.Base.Applicative (Control.Monad.Prompt.PromptT a b t)
instance (GHC.Base.Alternative t, Data.Traversable.Traversable t) => GHC.Base.Alternative (Control.Monad.Prompt.PromptT a b t)
instance (GHC.Base.Monad t, Data.Traversable.Traversable t) => GHC.Base.Monad (Control.Monad.Prompt.PromptT a b t)
instance (GHC.Base.MonadPlus t, Data.Traversable.Traversable t) => GHC.Base.MonadPlus (Control.Monad.Prompt.PromptT a b t)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Prompt.PromptT a b)
instance (Control.Monad.Error.Class.MonadError e t, Data.Traversable.Traversable t) => Control.Monad.Error.Class.MonadError e (Control.Monad.Prompt.PromptT a b t)
instance (Control.Monad.Reader.Class.MonadReader r t, Data.Traversable.Traversable t) => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Prompt.PromptT a b t)
instance (Control.Monad.State.Class.MonadState s t, Data.Traversable.Traversable t) => Control.Monad.State.Class.MonadState s (Control.Monad.Prompt.PromptT a b t)
instance (Control.Monad.Writer.Class.MonadWriter w t, Data.Traversable.Traversable t) => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Prompt.PromptT a b t)
instance GHC.Base.Applicative t => Control.Monad.Prompt.Class.MonadPrompt a b (Control.Monad.Prompt.PromptT a b t)
