-- 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.3

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
infixr 9 :+:

-- | 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 GHC.Base.Functor System.Console.Wizard.Internal.Password
instance GHC.Base.Functor System.Console.Wizard.Internal.LinePrewritten
instance GHC.Base.Functor System.Console.Wizard.Internal.Character
instance GHC.Base.Functor System.Console.Wizard.Internal.Line
instance GHC.Base.Functor System.Console.Wizard.Internal.OutputLn
instance GHC.Base.Functor System.Console.Wizard.Internal.Output
instance (GHC.Base.Functor f, GHC.Base.Functor g) => GHC.Base.Functor (f System.Console.Wizard.Internal.:+: g)
instance GHC.Base.Functor backend => GHC.Base.MonadPlus (System.Console.Wizard.Internal.Wizard backend)
instance GHC.Base.Functor backend => GHC.Base.Alternative (System.Console.Wizard.Internal.Wizard backend)
instance GHC.Base.Functor backend => GHC.Base.Applicative (System.Console.Wizard.Internal.Wizard backend)
instance GHC.Base.Functor backend => GHC.Base.Functor (System.Console.Wizard.Internal.Wizard backend)
instance GHC.Base.Functor backend => GHC.Base.Monad (System.Console.Wizard.Internal.Wizard backend)
instance GHC.Base.Functor System.Console.Wizard.Internal.ArbitraryIO
instance (System.Console.Wizard.Internal.Run b f, System.Console.Wizard.Internal.Run b g) => System.Console.Wizard.Internal.Run b (f System.Console.Wizard.Internal.:+: g)
instance GHC.Base.Functor f => f System.Console.Wizard.Internal.:<: f
instance (GHC.Base.Functor f, GHC.Base.Functor g) => f System.Console.Wizard.Internal.:<: (f System.Console.Wizard.Internal.:+: g)
instance (GHC.Base.Functor f, GHC.Base.Functor g, GHC.Base.Functor h, f System.Console.Wizard.Internal.:<: g) => f System.Console.Wizard.Internal.:<: (h System.Console.Wizard.Internal.:+: g)

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
infixr 9 :+:
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 (System.Console.Wizard.Internal.ArbitraryIO System.Console.Wizard.Internal.:<: b) => Control.Monad.IO.Class.MonadIO (System.Console.Wizard.Internal.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 System.Console.Wizard.Internal.Run (System.Console.Haskeline.InputT.InputT GHC.Types.IO) System.Console.Wizard.Haskeline.Haskeline
instance GHC.Base.Functor System.Console.Wizard.Haskeline.Haskeline
instance System.Console.Wizard.Haskeline.WithSettings System.Console.Wizard.Internal.:<: System.Console.Wizard.Haskeline.Haskeline
instance System.Console.Wizard.Internal.ArbitraryIO System.Console.Wizard.Internal.:<: System.Console.Wizard.Haskeline.Haskeline
instance System.Console.Wizard.Internal.Password System.Console.Wizard.Internal.:<: System.Console.Wizard.Haskeline.Haskeline
instance System.Console.Wizard.Internal.LinePrewritten System.Console.Wizard.Internal.:<: System.Console.Wizard.Haskeline.Haskeline
instance System.Console.Wizard.Internal.Character System.Console.Wizard.Internal.:<: System.Console.Wizard.Haskeline.Haskeline
instance System.Console.Wizard.Internal.Line System.Console.Wizard.Internal.:<: System.Console.Wizard.Haskeline.Haskeline
instance System.Console.Wizard.Internal.OutputLn System.Console.Wizard.Internal.:<: System.Console.Wizard.Haskeline.Haskeline
instance System.Console.Wizard.Internal.Output System.Console.Wizard.Internal.:<: System.Console.Wizard.Haskeline.Haskeline
instance GHC.Base.Functor System.Console.Wizard.Haskeline.WithSettings
instance GHC.Show.Show System.Console.Wizard.Haskeline.UnexpectedEOF
instance System.Console.Wizard.Internal.Run (System.Console.Haskeline.InputT.InputT GHC.Types.IO) System.Console.Wizard.Haskeline.WithSettings
instance GHC.Exception.Type.Exception System.Console.Wizard.Haskeline.UnexpectedEOF
instance System.Console.Wizard.Internal.Run (System.Console.Haskeline.InputT.InputT GHC.Types.IO) System.Console.Wizard.Internal.Output
instance System.Console.Wizard.Internal.Run (System.Console.Haskeline.InputT.InputT GHC.Types.IO) System.Console.Wizard.Internal.OutputLn
instance System.Console.Wizard.Internal.Run (System.Console.Haskeline.InputT.InputT GHC.Types.IO) System.Console.Wizard.Internal.Line
instance System.Console.Wizard.Internal.Run (System.Console.Haskeline.InputT.InputT GHC.Types.IO) System.Console.Wizard.Internal.Character
instance System.Console.Wizard.Internal.Run (System.Console.Haskeline.InputT.InputT GHC.Types.IO) System.Console.Wizard.Internal.LinePrewritten
instance System.Console.Wizard.Internal.Run (System.Console.Haskeline.InputT.InputT GHC.Types.IO) System.Console.Wizard.Internal.Password
instance System.Console.Wizard.Internal.Run (System.Console.Haskeline.InputT.InputT GHC.Types.IO) System.Console.Wizard.Internal.ArbitraryIO

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 System.Console.Wizard.Internal.Run GHC.Types.IO System.Console.Wizard.BasicIO.BasicIO
instance GHC.Base.Functor System.Console.Wizard.BasicIO.BasicIO
instance System.Console.Wizard.Internal.ArbitraryIO System.Console.Wizard.Internal.:<: System.Console.Wizard.BasicIO.BasicIO
instance System.Console.Wizard.Internal.Character System.Console.Wizard.Internal.:<: System.Console.Wizard.BasicIO.BasicIO
instance System.Console.Wizard.Internal.Line System.Console.Wizard.Internal.:<: System.Console.Wizard.BasicIO.BasicIO
instance System.Console.Wizard.Internal.OutputLn System.Console.Wizard.Internal.:<: System.Console.Wizard.BasicIO.BasicIO
instance System.Console.Wizard.Internal.Output System.Console.Wizard.Internal.:<: System.Console.Wizard.BasicIO.BasicIO
instance System.Console.Wizard.Internal.Run GHC.Types.IO System.Console.Wizard.Internal.Output
instance System.Console.Wizard.Internal.Run GHC.Types.IO System.Console.Wizard.Internal.OutputLn
instance System.Console.Wizard.Internal.Run GHC.Types.IO System.Console.Wizard.Internal.Line
instance System.Console.Wizard.Internal.Run GHC.Types.IO System.Console.Wizard.Internal.Character
instance System.Console.Wizard.Internal.Run GHC.Types.IO System.Console.Wizard.Internal.ArbitraryIO

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 System.Console.Wizard.Internal.Run (Control.Monad.Trans.State.Lazy.State System.Console.Wizard.Pure.PureState) System.Console.Wizard.Pure.Pure
instance GHC.Base.Functor System.Console.Wizard.Pure.Pure
instance System.Console.Wizard.Internal.Character System.Console.Wizard.Internal.:<: System.Console.Wizard.Pure.Pure
instance System.Console.Wizard.Internal.Line System.Console.Wizard.Internal.:<: System.Console.Wizard.Pure.Pure
instance System.Console.Wizard.Internal.OutputLn System.Console.Wizard.Internal.:<: System.Console.Wizard.Pure.Pure
instance System.Console.Wizard.Internal.Output System.Console.Wizard.Internal.:<: System.Console.Wizard.Pure.Pure
instance GHC.Show.Show System.Console.Wizard.Pure.UnexpectedEOI
instance System.Console.Wizard.Internal.Run (Control.Monad.Trans.State.Lazy.State System.Console.Wizard.Pure.PureState) System.Console.Wizard.Internal.Output
instance System.Console.Wizard.Internal.Run (Control.Monad.Trans.State.Lazy.State System.Console.Wizard.Pure.PureState) System.Console.Wizard.Internal.OutputLn
instance System.Console.Wizard.Internal.Run (Control.Monad.Trans.State.Lazy.State System.Console.Wizard.Pure.PureState) System.Console.Wizard.Internal.Line
instance System.Console.Wizard.Internal.Run (Control.Monad.Trans.State.Lazy.State System.Console.Wizard.Pure.PureState) System.Console.Wizard.Internal.Character
instance GHC.Exception.Type.Exception System.Console.Wizard.Pure.UnexpectedEOI