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


-- | Cross-request user interactions for Happstack
--   
--   A mechanism for user interactions that extend through multiple
--   request/response cycles on the Happstack server, inspired by Chris
--   Eidhof.
@package happstack-dlg
@version 0.1.2

module Happstack.Server.Dialogues

-- | A value of a <a>Dlg</a> type represents a dialogue between the user
--   and the application, after which the application builds a value of
--   type a. The trivial case is that the value is already known.
--   Alternatively, it may be that there is some action to be performed, or
--   else that the user needs to be asked or told something.
data Dlg m a

-- | A value of <a>Page</a> type represents a way of rendering a page,
--   given a request URI that should be used for subsequent requests in
--   order to reassociate them with the current dialogue.
type Page m = String -> ServerPartT m Response
perform :: (Monad m) => ServerPartT m a -> Dlg m a

-- | Converts methods for rendering and parsing the result of a page into a
--   <a>Dlg</a> step.
showPage :: (Monad m) => Page m -> ServerPartT m a -> Dlg m a

-- | A <a>DialogueManager</a> is responsible for maintaining the state for
--   <a>Dlg</a> sequences for all users. To do this, it keeps for each user
--   a session object encapsulating their dialogues, and associates each
--   user with their session using cookies.
data DialogueManager m

-- | Create a new <a>DialogueManager</a> to manage a set of dialogues in
--   the web application. This also spawns the session reaper, which cleans
--   up sessions that haven't been touched for a given time period.
makeDialogueManager :: NominalDiffTime -> IO (DialogueManager m)

-- | Closes a DialogueManager, which will cause it to cease accepting any
--   incoming requests, and also to terminate the session reaper thread.
closeDialogueManager :: DialogueManager m -> IO ()

-- | The <a>dialogue</a> function builds a <a>ServerPartT</a> that handles
--   a given dialogue. In general, it can be combined in normal ways with
--   guards and such, so long as changes in the request parameters won't
--   cause it to be missed when future requests are made in the same
--   dialogue.
dialogue :: (MonadIO m) => DialogueManager m -> Dlg m () -> ServerPartT m Response
instance (MonadIO m) => MonadIO (Dlg m)
instance MonadTrans Dlg
instance (Monad m) => Monad (Dlg m)

module Happstack.Server.Dialogues.Scaffold
escapeHtml :: String -> String

-- | The <a>scaffold</a> function builds a user interaction to display and
--   collect information. In a finished web application, this should
--   generally be replaced with a better mechanism for rendering pages,
--   such as a templating engine, XSLT, or something of the sort.
scaffold :: (Scaffolded a, Monad m) => String -> a -> Dlg m a

-- | The <a>Scaffolded</a> type class represents data that can be included
--   in a form. To make it easy to compose several of these in a page,
--   rendering and parsing are parameterized with prefix strings so that
--   they may be made unique across a page.
class Scaffolded a
render :: (Scaffolded a) => String -> a -> String
parse :: (Scaffolded a, Monad m) => String -> a -> ServerPartT m a

-- | Wrapper type to present a list of options.
data Choice a
Choice :: [a] -> Int -> Choice a
toChoice :: (Bounded a, Enum a, Eq a) => a -> Choice a
fromChoice :: Choice a -> a
chooseFrom :: [a] -> Choice a
instance (Show a) => Show (Choice a)
instance (Eq a, Show a) => Scaffolded (Choice a)
instance (Scaffolded a, Scaffolded b, Scaffolded c) => Scaffolded (a, b, c)
instance (Scaffolded a, Scaffolded b) => Scaffolded (a, b)
instance Scaffolded Int
instance Scaffolded Bool
instance Scaffolded ByteString
instance Scaffolded String
instance Scaffolded ()

module Happstack.Server.Dialogues.Formlets
showForm :: (Monad m) => XHtmlForm Identity a -> Dlg m (Maybe a)