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


-- | Haskell Server Pages is a library for writing dynamic server-side web pages.
--   
--   Haskell Server Pages (HSP) is an extension of vanilla Haskell,
--   targetted at the task of writing dynamic server-side web pages.
--   Features include:
--   
--   <ul>
--   <li>Embedded XML syntax</li>
--   <li>A (low-to-mid-level) programming model for writing dynamic web
--   pages</li>
--   <li>A cgi-handler utility (as a separate package, hsp-cgi)</li>
--   </ul>
--   
--   For details on usage, please see the website, and the author's thesis.
@package hsp
@version 0.5.2

module HSP.Env.NumberGen
data NumberGen
NumberGen :: IO Int -> NumberGen
incNumber :: NumberGen -> IO Int


-- | An interface to a request object as held in the HSP environment.
module HSP.Env.Request

-- | A record representing an interface to an HTTP request. This allows us
--   to use many different underlying types for these requests, all we need
--   is to supply conversions to this interface. This is useful for when we
--   run as CGI, or when we run inside a server app.
data Request
Request :: (String -> [String]) -> [(String, String)] -> Request
getParameterL :: Request -> String -> [String]
getHeaders :: Request -> [(String, String)]

-- | Get a parameter from the request query string (GET) or body (POST). |
--   Returns <tt>Nothing</tt> if the parameter is not set.
getParameter :: Request -> String -> Maybe String

-- | Unsafe version of getParameter, essentially fromJust.(getParameter r)
--   but throws a ParameterLookupFailed exception if the parameter is not
--   set.
getParameter_ :: Request -> String -> String

-- | Return a value instead of a string.
readParameter :: (Read a) => Request -> String -> Maybe a

-- | Return a list of values read from their string representations.
readParameterL :: (Read a) => Request -> String -> [a]

-- | Unsafe version of readParameter
readParameter_ :: (Read a) => Request -> String -> a

module HSP.Env

-- | The runtime environment for HSP pages.
data HSPEnv
HSPEnv :: Request -> NumberGen -> HSPEnv
getReq :: HSPEnv -> Request
getNG :: HSPEnv -> NumberGen
mkSimpleEnv :: IO HSPEnv


-- | Escaping between CDATA <a>=</a> PCDATA
module HSP.XML.PCDATA

-- | Take a normal string and transform it to PCDATA by escaping special
--   characters. calls <a>escaper</a> with <a>xmlEscapeChars</a> See also:
--   <a>escaper</a>
escape :: String -> String

-- | Take a PCDATA string and translate all escaped characters in it to the
--   normal characters they represent. Does no error checking of input
--   string, will fail if input is not valid PCDATA. calls <a>unescaper</a>
--   with <a>xmlEscapeChars</a> See also: <a>unescaper</a>
unescape :: String -> String

-- | Take a normal string and transform it to PCDATA by escaping special
--   characters. See also: <a>escape</a>, <a>xmlEscapeChars</a>
escaper :: [(Char, String)] -> String -> String

-- | Take a PCDATA string and translate all escaped characters in it to the
--   normal characters they represent. Does no error checking of input
--   string, will fail if input is not valid PCDATA. See also:
--   <a>unescape</a>, <a>xmlEscapeChars</a>
unescaper :: [(Char, String)] -> String -> String
xmlEscapeChars :: [(Char, String)]


-- | Datatypes and type classes comprising the basic model behind the
--   scenes of Haskell Server Pages tags.
module HSP.XML

-- | The XML datatype representation. Is either an Element or CDATA.
data XML
Element :: Name -> Attributes -> Children -> XML
CDATA :: Bool -> String -> XML

-- | The XMLMetaData datatype
--   
--   Specify the DOCTYPE, content-type, and preferred render for XML data.
--   
--   See also: <tt>HSP.Monad.setMetaData</tt> and
--   <tt>HSP.Monad.withMetaData</tt>
data XMLMetaData
XMLMetaData :: (Bool, String) -> String -> (XML -> String) -> XMLMetaData

-- | (show doctype when rendering, DOCTYPE string)
doctype :: XMLMetaData -> (Bool, String)
contentType :: XMLMetaData -> String
preferredRenderer :: XMLMetaData -> XML -> String
type Domain = Maybe String
type Name = (Domain, String)
type Attributes = [Attribute]
type Children = [XML]

-- | Embeds a string as a CDATA XML value.
pcdata :: String -> XML
cdata :: String -> XML
newtype Attribute
MkAttr :: (Name, AttrValue) -> Attribute

-- | Represents an attribue value.
data AttrValue
Value :: Bool -> String -> AttrValue
attrVal :: String -> AttrValue

-- | Create an attribue value from a string.
pAttrVal :: String -> AttrValue

-- | Pretty-prints XML values.
renderXML :: XML -> String
isElement :: XML -> Bool

-- | Test whether an XML value is an Element or CDATA
isCDATA :: XML -> Bool
instance [overlap ok] Show Attribute
instance [overlap ok] Show XML
instance [overlap ok] Show AttrValue


-- | Attempt to render XHTML as well-formed HTML 4.01:
--   
--   <ol>
--   <li>no short tags are used, e.g., &lt;script&gt;&lt;/script&gt;
--   instead of &lt;script /&gt;</li>
--   <li>the end tag is forbidden for some elements, for these we:</li>
--   </ol>
--   
--   <ul>
--   <li>render only the open tag, e.g., &lt;br&gt;</li>
--   <li>throw an error if the tag contains children</li>
--   </ul>
--   
--   <ol>
--   <li>optional end tags are always rendered</li>
--   </ol>
--   
--   Currently no validation is performed.
module HSP.HTML

-- | Pretty-prints HTML values.
--   
--   Error Handling:
--   
--   Some tags (such as img) can not contain children in HTML. However,
--   there is nothing to stop the caller from passing in XML which contains
--   an img tag with children. There are three basic ways to handle this:
--   
--   <ol>
--   <li>drop the bogus children silently</li>
--   <li>call <a>error</a> / raise an exception</li>
--   <li>render the img tag with children -- even though it is invalid</li>
--   </ol>
--   
--   Currently we are taking approach #3, since no other attempts to
--   validate the data are made in this function. Instead, you can run the
--   output through a full HTML validator to detect the errors.
--   
--   #1 seems like a poor choice, since it makes is easy to overlook the
--   fact that data went missing.
--   
--   We could raising errors, but you have to be in the IO monad to catch
--   them. Also, you have to use evaluate if you want to check for errors.
--   This means you can not start sending the page until the whole page has
--   been rendered. And you have to store the whole page in RAM at once.
--   Similar problems occur if we return Either instead. We mostly care
--   about catching errors and showing them in the browser during testing,
--   so perhaps this can be configurable.
--   
--   Another solution would be a compile time error if an empty-only tag
--   contained children.
--   
--   FIXME: also verify that the domain is correct
--   
--   FIXME: what to do if a namespace is encountered
renderAsHTML :: XML -> String
htmlEscapeChars :: [(Char, String)]
html4Strict :: Maybe XMLMetaData
html4StrictFrag :: Maybe XMLMetaData

module HSP.HJScript
newGlobalVar :: HSP (Var t, Block ())
newGlobalVarWith :: Exp t -> HSP (Var t, Block ())
newGlobVarName :: HSP String
type ElemRef = String
genId :: HSP ElemRef
ref :: HSP XML -> HSP (ElemRef, XML)
setId :: (SetAttr m xml, EmbedAsAttr m (Attr String v)) => xml -> v -> XMLGenT m (XML m)
onEvent :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => Event -> xml -> HJScript t -> XMLGenT m (XML m)
onBlur :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onChange :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onClick :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onDblClick :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onError :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onFocus :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onKeyDown :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onKeyPress :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onKeyUp :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onLoad :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onMouseDown :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onMouseMove :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onMouseOut :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onMouseOver :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onMouseUp :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onReset :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onResize :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onSelect :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onSubmit :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onUnload :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
onAbort :: (SetAttr m xml, EmbedAsAttr m (Attr String (HJScript t))) => xml -> HJScript t -> XMLGenT m (XML m)
instance [overlap ok] (Monad m) => IsAttrValue m (HJScript (Exp t))
instance [overlap ok] (Monad m) => IsAttrValue m (HJScript ())
instance [overlap ok] (Monad m) => IsAttrValue m (Block t)
instance [overlap ok] (Monad m) => EmbedAsChild (HSPT' m) (HJScript ())
instance [overlap ok] (Monad m) => EmbedAsChild (HSPT' m) (Block t)

module HSP

-- | The HSP monad is a reader wrapper around the IO monad, but extended
--   with an XMLGenerator wrapper. type HSP' = ReaderT HSPEnv IO type HSP =
--   XMLGenT HSP'
type HSP = HSPT IO
type HSPT m = XMLGenT (HSPT' m)
type HSPT' m = RWST HSPEnv () (Maybe XMLMetaData) m

-- | Runs a HSP computation in a particular environment. Since HSP wraps
--   the IO monad, the result of running it will be an IO computation.
runHSP :: Maybe XMLMetaData -> HSP a -> HSPEnv -> IO (Maybe XMLMetaData, a)
evalHSP :: Maybe XMLMetaData -> HSP a -> IO (Maybe XMLMetaData, a)
runHSPT :: (Monad m) => Maybe XMLMetaData -> HSPT m a -> HSPEnv -> m (Maybe XMLMetaData, a)
evalHSPT :: (MonadIO m) => Maybe XMLMetaData -> HSPT m a -> m (Maybe XMLMetaData, a)

-- | Supplies the HSP environment.
getEnv :: HSP HSPEnv
getParam :: String -> HSP (Maybe String)
getIncNumber :: HSP Int

-- | Execute an IO computation within the HSP monad.
doIO :: IO a -> HSP a

-- | Catch a user-caused exception.
catch :: HSP a -> (Exception -> HSP a) -> HSP a
setMetaData :: (Monad m) => (Maybe XMLMetaData) -> HSPT m ()
withMetaData :: (Monad m) => Maybe XMLMetaData -> HSPT m a -> HSPT m a
class (Monad m) => IsAttrValue m a
toAttrValue :: (IsAttrValue m a) => a -> HSPT m AttrValue
extract :: (GetAttrValue a) => Name -> Attributes -> (Maybe a, Attributes)
genElement :: (XMLGen m) => Name -> [XMLGenT m [Attribute m]] -> [XMLGenT m [Child m]] -> XMLGenT m (XML m)
genEElement :: (XMLGen m) => Name -> [XMLGenT m [Attribute m]] -> XMLGenT m (XML m)