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

module Happstack.Server.Dialogs

-- | A value of a <a>Dlg</a> type represents a dialog 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 unique ID that should be included in responses in order to
--   reassociate the response with the current dialog.
type Page m = Int -> 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>DialogManager</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 dialogs, and associates each user
--   with a dialog using cookies.
data DialogManager m

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

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

-- | The <a>dialog</a> function builds a <a>ServerPartT</a> that handles a
--   given dialog. 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
--   dialog.
dialog :: (MonadIO m) => DialogManager m -> Dlg m () -> ServerPartT m Response
instance (MonadIO m) => MonadIO (Dlg m)
instance MonadTrans Dlg
instance (Monad m) => Monad (Dlg m)

module Happstack.Server.Dialogs.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 -> ServerPartT m 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 String
instance Scaffolded ()