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


-- | High level, generic library for interrogative user interfaces
--   
--   <tt>wizards</tt> is a package designed for the quick and painless
--   development of <i>interrogative</i> programs, which revolve around a
--   "dialogue" with the user, who is asked a series of questions in a
--   sequence much like an installation wizard.
--   
--   Everything from interactive system scripts, to installation wizards,
--   to full-blown shells can be implemented with the support of
--   <tt>wizards</tt>.
--   
--   It is developed transparently on top of a free monad, which separates
--   out the semantics of the program from any particular interface. A
--   variety of backends exist, including console-based
--   <a>System.Console.Wizard.Haskeline</a> and
--   <a>System.Console.Wizard.BasicIO</a>, and the pure
--   <a>System.Console.Wizard.Pure</a>. It is also possible to write your
--   own backends, or extend existing back-ends with new features. While
--   both built-in IO backends operate on a console, there is no reason why
--   <tt>wizards</tt> cannot also be used for making GUI wizard interfaces.
--   
--   See the github page for examples on usage:
--   
--   <a>http://www.github.com/liamoc/wizards</a>
--   
--   For creating backends, the module
--   <a>System.Console.Wizard.Internal</a> has a brief tutorial.
@package wizards
@version 1.0

module System.Console.Wizard.Internal

-- | A <tt>Wizard b a</tt> is a conversation with the user via back-end
--   <tt>b</tt> that will result in a data type <tt>a</tt>, or may fail. A
--   <a>Wizard</a> is made up of one or more "primitives" (see below),
--   composed using the <a>Applicative</a>, <a>Monad</a> and
--   <a>Alternative</a> instances. The <a>Alternative</a> instance is, as
--   you might expect, a maybe-style cascade. If the first wizard fails,
--   the next one is tried. <a>mzero</a> can be used to induce failure
--   directly.
--   
--   The <a>Wizard</a> constructor is exported here for use when developing
--   backends, but it is better for end-users to simply pretend that
--   <a>Wizard</a> is an opaque data type. Don't depend on this unless you
--   have no other choice.
--   
--   <a>Wizard</a>s are, internally, just a maybe transformer over a free
--   monad built from some coproduct of functors, each of which is a
--   primitive action.
newtype Wizard backend a
Wizard :: (MaybeT (Free backend) a) -> Wizard backend a

-- | A string for a prompt
type PromptString = String

-- | Coproduct of two functors
data (:+:) f g w
Inl :: (f w) -> :+: f g w
Inr :: (g w) -> :+: f g w

-- | Subsumption of two functors. You shouldn't define any of your own
--   instances of this when writing back-ends, rely only on
--   GeneralizedNewtypeDeriving.
class (Functor sub, Functor sup) => :<: sub sup

-- | Injection function for free monads, see "Data Types a la Carte" from
--   Walter Swierstra,
--   <tt>http://www.cs.ru.nl/~W.Swierstra/Publications/DataTypesALaCarte.pdf</tt>
inject :: g :<: f => g (Free f a) -> Free f a

-- | A class for implementing actions on a backend. E.g Run IO Output
--   provides an interpreter for the Output action in the IO monad.
class Run a b
runAlgebra :: Run a b => b (a v) -> a v

-- | Run a wizard using some back-end.
run :: (Functor f, Monad b, Run b f) => Wizard f a -> b (Maybe a)
data Output w
Output :: String -> w -> Output w
data OutputLn w
OutputLn :: String -> w -> OutputLn w
data Line w
Line :: PromptString -> (String -> w) -> Line w
data LinePrewritten w
LinePrewritten :: PromptString -> String -> String -> (String -> w) -> LinePrewritten w
data Password w
Password :: PromptString -> (Maybe Char) -> (String -> w) -> Password w
data Character w
Character :: PromptString -> (Char -> w) -> Character w
data ArbitraryIO w
ArbitraryIO :: (IO a) -> (a -> w) -> ArbitraryIO w
instance [overlap ok] Functor backend => Monad (Wizard backend)
instance [overlap ok] Functor backend => Functor (Wizard backend)
instance [overlap ok] Functor backend => Applicative (Wizard backend)
instance [overlap ok] Functor backend => Alternative (Wizard backend)
instance [overlap ok] Functor backend => MonadPlus (Wizard backend)
instance [overlap ok] (Functor f, Functor g) => Functor (f :+: g)
instance [overlap ok] Functor Output
instance [overlap ok] Functor OutputLn
instance [overlap ok] Functor Line
instance [overlap ok] Functor Character
instance [overlap ok] Functor LinePrewritten
instance [overlap ok] Functor Password
instance [overlap ok] Functor ArbitraryIO
instance [overlap ok] (Run b f, Run b g) => Run b (f :+: g)
instance [overlap ok] (Functor f, Functor g, Functor h, f :<: g) => f :<: (h :+: g)
instance [overlap ok] (Functor f, Functor g) => f :<: (f :+: g)
instance [overlap ok] Functor f => f :<: f

module System.Console.Wizard

-- | A <tt>Wizard b a</tt> is a conversation with the user via back-end
--   <tt>b</tt> that will result in a data type <tt>a</tt>, or may fail. A
--   <a>Wizard</a> is made up of one or more "primitives" (see below),
--   composed using the <a>Applicative</a>, <a>Monad</a> and
--   <a>Alternative</a> instances. The <a>Alternative</a> instance is, as
--   you might expect, a maybe-style cascade. If the first wizard fails,
--   the next one is tried. <a>mzero</a> can be used to induce failure
--   directly.
--   
--   The <a>Wizard</a> constructor is exported here for use when developing
--   backends, but it is better for end-users to simply pretend that
--   <a>Wizard</a> is an opaque data type. Don't depend on this unless you
--   have no other choice.
--   
--   <a>Wizard</a>s are, internally, just a maybe transformer over a free
--   monad built from some coproduct of functors, each of which is a
--   primitive action.
newtype Wizard backend a
Wizard :: (MaybeT (Free backend) a) -> Wizard backend a

-- | A string for a prompt
type PromptString = String

-- | Run a wizard using some back-end.
run :: (Functor f, Monad b, Run b f) => Wizard f a -> b (Maybe a)

-- | Subsumption of two functors. You shouldn't define any of your own
--   instances of this when writing back-ends, rely only on
--   GeneralizedNewtypeDeriving.
class (Functor sub, Functor sup) => :<: sub sup

-- | Coproduct of two functors
data (:+:) f g w
data Line w

-- | Read one line of input from the user. Cannot fail (but may throw
--   exceptions, depending on the backend).
line :: Line :<: b => PromptString -> Wizard b String
data LinePrewritten w

-- | Read one line of input, with some default text already present, before
--   and/or after the editing cursor.
linePrewritten :: LinePrewritten :<: b => PromptString -> String -> String -> Wizard b String
data Password w

-- | Read one line of password input, with an optional mask character.
password :: Password :<: b => PromptString -> Maybe Char -> Wizard b String
data Character w

-- | Read a single character only from input. Cannot fail (but may throw
--   exceptions, depending on the backend).
character :: Character :<: b => PromptString -> Wizard b Char
data Output w

-- | Output a string. Does not fail.
output :: Output :<: b => String -> Wizard b ()
data OutputLn w

-- | Output a string followed by a newline. Does not fail.
outputLn :: OutputLn :<: b => String -> Wizard b ()
data ArbitraryIO w

-- | Retry produces a wizard that will retry the entire conversation again
--   if it fails. It is simply <tt>retry x = x &lt;|&gt; retry x</tt>.
retry :: Functor b => Wizard b a -> Wizard b a

-- | Same as <a>retry</a>, except an error message can be specified.
retryMsg :: OutputLn :<: b => String -> Wizard b a -> Wizard b a

-- | <tt>x `defaultTo` y</tt> will return <tt>y</tt> if <tt>x</tt> fails,
--   e.g <tt>parseRead line `defaultTo` 0</tt>.
defaultTo :: Functor b => Wizard b a -> a -> Wizard b a

-- | Like <a>fmap</a>, except the function may be partial (<a>Nothing</a>
--   causes the wizard to fail).
parser :: Functor b => (a -> Maybe c) -> Wizard b a -> Wizard b c

-- | <tt>validator p</tt> causes a wizard to fail if the output value does
--   not satisfy the predicate <tt>p</tt>.
validator :: Functor b => (a -> Bool) -> Wizard b a -> Wizard b a

-- | Simply <tt>validator (not . null)</tt>, makes a wizard fail if it gets
--   an empty string.
nonEmpty :: Functor b => Wizard b [a] -> Wizard b [a]

-- | Makes a wizard fail if it gets an ordered quantity outside of the
--   given range.
inRange :: (Ord a, Functor b) => (a, a) -> Wizard b a -> Wizard b a

-- | Simply <tt>parser readP</tt>. Attaches a simple <tt>read</tt> parser
--   to a <a>Wizard</a>.
parseRead :: (Read a, Functor b) => Wizard b String -> Wizard b a

-- | Translate a maybe value into wizard success/failure.
liftMaybe :: Functor b => Maybe a -> Wizard b a

-- | Ensures that a maybe value satisfies a given predicate.
ensure :: (a -> Bool) -> a -> Maybe a

-- | A read-based parser for the <a>parser</a> modifier.
readP :: Read a => String -> Maybe a
instance [overlap ok] ArbitraryIO :<: b => MonadIO (Wizard b)

module System.Console.Wizard.Haskeline

-- | The Haskeline back-end will throw this exception if EOF is encountered
--   when it is not expected. Specifically, when actions such as
--   <a>getInputLine</a> return <a>Nothing</a>.
data UnexpectedEOF
UnexpectedEOF :: UnexpectedEOF

-- | Haskeline supports all the following features completely.
data Haskeline a

-- | A simple identity function, used to restrict types if the type
--   inferred by GHC is too general. You could achieve the same effect with
--   a type signature, but this is slightly less typing.
haskeline :: Wizard Haskeline a -> Wizard Haskeline a

-- | Modifies a wizard so that it will run with different Haskeline
--   <a>Settings</a> to the top level input monad.
withSettings :: WithSettings :<: b => Settings IO -> Wizard b a -> Wizard b a
data WithSettings w
WithSettings :: (Settings IO) -> w -> WithSettings w
instance [overlap ok] Typeable UnexpectedEOF
instance [overlap ok] Show UnexpectedEOF
instance [overlap ok] Functor WithSettings
instance [overlap ok] Output :<: Haskeline
instance [overlap ok] OutputLn :<: Haskeline
instance [overlap ok] Line :<: Haskeline
instance [overlap ok] Character :<: Haskeline
instance [overlap ok] LinePrewritten :<: Haskeline
instance [overlap ok] Password :<: Haskeline
instance [overlap ok] ArbitraryIO :<: Haskeline
instance [overlap ok] WithSettings :<: Haskeline
instance [overlap ok] Functor Haskeline
instance [overlap ok] Run (InputT IO) Haskeline
instance [overlap ok] Run (InputT IO) WithSettings
instance [overlap ok] Run (InputT IO) ArbitraryIO
instance [overlap ok] Run (InputT IO) Password
instance [overlap ok] Run (InputT IO) LinePrewritten
instance [overlap ok] Run (InputT IO) Character
instance [overlap ok] Run (InputT IO) Line
instance [overlap ok] Run (InputT IO) OutputLn
instance [overlap ok] Run (InputT IO) Output
instance [overlap ok] Exception UnexpectedEOF

module System.Console.Wizard.BasicIO

-- | The <a>BasicIO</a> backend supports only simple input and output.
--   Support for <a>Password</a> and <a>LinePrewritten</a> features can be
--   added with a shim from <a>Shim</a>.
data BasicIO a

-- | A simple identity function, used to restrict types if the type
--   inferred by GHC is too general. You could achieve the same effect with
--   a type signature, but this is slightly less typing.
basicIO :: Wizard BasicIO a -> Wizard BasicIO a
instance [overlap ok] Output :<: BasicIO
instance [overlap ok] OutputLn :<: BasicIO
instance [overlap ok] Line :<: BasicIO
instance [overlap ok] Character :<: BasicIO
instance [overlap ok] ArbitraryIO :<: BasicIO
instance [overlap ok] Functor BasicIO
instance [overlap ok] Run IO BasicIO
instance [overlap ok] Run IO ArbitraryIO
instance [overlap ok] Run IO Character
instance [overlap ok] Run IO Line
instance [overlap ok] Run IO OutputLn
instance [overlap ok] Run IO Output

module System.Console.Wizard.Pure

-- | The <a>Pure</a> backend supports only simple input and output. Support
--   for <a>Password</a> and <a>LinePrewritten</a> features can be added
--   with a shim from <a>System.Console.Wizard.Shim</a>.
data Pure a

-- | Thrown if the wizard ever unexpectedly runs out of input.
data UnexpectedEOI
UnexpectedEOI :: UnexpectedEOI

-- | Run a wizard in the Pure backend
runPure :: Wizard Pure a -> String -> (Maybe a, String)

-- | The pure backend is actually just a simple state monad, with the
--   following state.
type PureState = ([String], Seq Char)
instance [overlap ok] Typeable UnexpectedEOI
instance [overlap ok] Show UnexpectedEOI
instance [overlap ok] Output :<: Pure
instance [overlap ok] OutputLn :<: Pure
instance [overlap ok] Line :<: Pure
instance [overlap ok] Character :<: Pure
instance [overlap ok] Functor Pure
instance [overlap ok] Run (State PureState) Pure
instance [overlap ok] Run (State PureState) Character
instance [overlap ok] Run (State PureState) Line
instance [overlap ok] Run (State PureState) OutputLn
instance [overlap ok] Run (State PureState) Output
instance [overlap ok] Exception UnexpectedEOI