-- 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 Prompt monad, which
--   separates out the semantics of the program from any particular
--   interface. A variety of backends exist, including
--   <a>System.Console.Wizard.Haskeline</a> and
--   <a>System.Console.Wizard.BasicIO</a>. It is also possible to write
--   your own backends. While both built-in 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 0.1

module System.Console.Wizard.Internal

-- | Internally, a <tt>Wizard</tt> is essentially a prompt monad with a
--   <a>WizardAction</a>. A constructor exists for each primitive action,
--   as well as a special "escape hatch" constructor (<a>Backend</a>) used
--   for writing backend-specific primitives and modifiers. Each back-end
--   has a corresponding data type, used as a type parameter for
--   <tt>Wizard</tt>. This data type is usually opaque, but internally
--   specifies additional primitive actions that are specific to the
--   back-end. <a>WizardAction</a> is parameterised by this data type (for
--   use in the <a>Backend</a> constructor), the prompt monad itself (so
--   that modifiers can be made as well as primitives) and the return type
--   of the action.
data WizardAction :: ((* -> *) -> * -> *) -> (* -> *) -> * -> *
Line :: PromptString -> WizardAction b m String
LinePreset :: PromptString -> String -> String -> WizardAction b m String
Password :: PromptString -> Maybe Char -> WizardAction b m String
Character :: PromptString -> WizardAction b m Char
Output :: String -> WizardAction b m ()
OutputLn :: String -> WizardAction b m ()
Backend :: b m a -> WizardAction b m a
type PromptString = String

module System.Console.Wizard

-- | A <tt>Wizard a</tt> is a conversation with the user 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.
--   
--   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 prompt
--   monad for each primitive action.
newtype Wizard backend a
Wizard :: (MaybeT (RecPrompt (WizardAction backend)) a) -> Wizard backend a
type PromptString = String

-- | Read one line of input from the user.
line :: PromptString -> Wizard b String

-- | Read one line of input, with some default text already present, before
--   and/or after the editing cursor. Backends are not required to display
--   this default text, or position the cursor anywhere, it is merely a
--   suggestion.
linePrewritten :: PromptString -> String -> String -> Wizard b String

-- | Read one line of password input, with an optional mask character. The
--   exact masking behavior of the password may vary from backend to
--   backend. The masking character does not have to be honoured.
password :: PromptString -> Maybe Char -> Wizard b String

-- | Read a single character only from input.
character :: PromptString -> Wizard b Char

-- | Output a string, if the backend used supports output.
output :: String -> Wizard b ()

-- | Output a string followed by a newline, if the backend used supports
--   such output.
outputLn :: String -> Wizard b ()

-- | Retry produces a wizard that will retry the entire conversation again
--   if it fails. Conceptually, it could thought of as <tt>retry x = x
--   &lt;|&gt; retry x</tt>, however it also prints a user-friendly error
--   message in the event of failure.
retry :: Wizard b a -> Wizard b a

-- | Same as <a>retry</a>, except the error message can be specified.
retryMsg :: 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 :: 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 :: (a -> Maybe c) -> Wizard b a -> Wizard b c

-- | <tt>validator p w</tt> causes a wizard to fail if the output value
--   does not satisfy the predicate <tt>p</tt>.
validator :: (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 :: Wizard b [a] -> Wizard b [a]

-- | Makes a wizard fail if it gets an ordered quantity outside of the
--   given range.
inRange :: Ord a => (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 => Wizard b String -> Wizard b a

-- | Translate a maybe value into wizard success/failure.
liftMaybe :: 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 Monad (Wizard backend)
instance Functor (Wizard backend)
instance Applicative (Wizard backend)
instance Alternative (Wizard backend)
instance MonadPlus (Wizard backend)
instance MonadPrompt (WizardAction s (RecPrompt (WizardAction s))) (Wizard s)

module System.Console.Wizard.Haskeline

-- | A Haskeline backend for <tt>wizards</tt>, supporting input, output,
--   default text, and password input. In addition, Haskeline settings can
--   be modified for a single wizard, and arbitrary IO can be performed
--   using the <a>MonadIO</a> instance.
data Haskeline m r

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

-- | Runs a Wizard action in the Haskeline backend.
runHaskeline :: Wizard Haskeline a -> InputT IO (Maybe a)

-- | Modifies a wizard so that it will run with different Haskeline
--   <a>Settings</a> to the top level input monad.
withSettings :: Settings IO -> Wizard Haskeline a -> Wizard Haskeline a
instance Typeable UnexpectedEOF
instance Show UnexpectedEOF
instance MonadIO (Wizard Haskeline)
instance Exception UnexpectedEOF

module System.Console.Wizard.BasicIO

-- | A very simple standard IO backend for <tt>wizards</tt>, supporting
--   input and output. Default text and password masks are ignored. A more
--   full-featured back-end is based on Haskeline. Arbitrary IO actions can
--   be performed in wizards via a <a>MonadIO</a> instance.
data BasicIO (m :: * -> *) r

-- | Runs a Wizard action in the BasicIO backend.
runBasicIO :: Wizard BasicIO a -> IO (Maybe a)
instance MonadIO (Wizard BasicIO)