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


-- | 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 :: Text -> Builder

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


-- | 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 :: NSName -> Attributes -> Children -> XML
CDATA :: Bool -> Text -> XML

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

-- | (show doctype when rendering, DOCTYPE string)
doctype :: XMLMetaData -> (Bool, Text)
contentType :: XMLMetaData -> Text
preferredRenderer :: XMLMetaData -> XML -> Builder
type Namespace = Maybe Text
type NSName = (Namespace, Text)
type Attributes = [Attribute]
type Children = [XML]

-- | Embeds a string as a CDATA XML value.
pcdata :: Text -> XML

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

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

-- | Create an attribue value from a string.
attrVal :: Text -> AttrValue

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

-- | Pretty-prints XML values.
renderXML :: XML -> Text

-- | Test whether an XML value is an Element or CDATA
isElement :: XML -> Bool

-- | Test whether an XML value is an Element or CDATA
isCDATA :: XML -> Bool
fromStringLit :: String -> Text
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.HTML4

-- | 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 -> Text
htmlEscapeChars :: [(Char, Builder)]
html4Strict :: Maybe XMLMetaData
html4StrictFrag :: Maybe XMLMetaData


-- | The class and monad transformer that forms the basis of the literal
--   XML syntax translation. Literal tags will be translated into functions
--   of the GenerateXML class, and any instantiating monads with associated
--   XML types can benefit from that syntax.
module HSP.XMLGenerator

-- | The monad transformer that allows a monad to generate XML values.
newtype XMLGenT m a
XMLGenT :: (m a) -> XMLGenT m a

-- | un-lift.
unXMLGenT :: XMLGenT m a -> m a

-- | map the inner monad
mapXMLGenT :: (m a -> n b) -> XMLGenT m a -> XMLGenT n b
type Name a = (Maybe a, a)

-- | Generate XML values in some XMLGenerator monad.
class Monad m => XMLGen m where type family XMLType m type family StringType m data family ChildType m data family AttributeType m genEElement n ats = genElement n ats []
genElement :: XMLGen m => Name (StringType m) -> [XMLGenT m [AttributeType m]] -> [XMLGenT m [ChildType m]] -> XMLGenT m (XMLType m)
genEElement :: XMLGen m => Name (StringType m) -> [XMLGenT m [AttributeType m]] -> XMLGenT m (XMLType m)
xmlToChild :: XMLGen m => XMLType m -> ChildType m
pcdataToChild :: XMLGen m => StringType m -> ChildType m

-- | Type synonyms to avoid writing out the XMLnGenT all the time
type GenXML m = XMLGenT m (XMLType m)
type GenXMLList m = XMLGenT m [XMLType m]
type GenChild m = XMLGenT m (ChildType m)
type GenChildList m = XMLGenT m [ChildType m]
type GenAttribute m = XMLGenT m (AttributeType m)
type GenAttributeList m = XMLGenT m [AttributeType m]

-- | Embed values as child nodes of an XML element. The parent type will be
--   clear from the context so it is not mentioned.
class XMLGen m => EmbedAsChild m c
asChild :: EmbedAsChild m c => c -> GenChildList m
data Attr n a
(:=) :: n -> a -> Attr n a

-- | Similarly embed values as attributes of an XML element.
class XMLGen m => EmbedAsAttr m a
asAttr :: EmbedAsAttr m a => a -> GenAttributeList m
class (XMLGen m, SetAttr m (XMLType m), AppendChild m (XMLType m), EmbedAsChild m (XMLType m), EmbedAsChild m [XMLType m], EmbedAsChild m Text, EmbedAsChild m Char, EmbedAsChild m (), EmbedAsAttr m (Attr Text Text), EmbedAsAttr m (Attr Text Int), EmbedAsAttr m (Attr Text Bool)) => XMLGenerator m

-- | Set attributes on XML elements
class XMLGen m => SetAttr m elem where setAttr e a = setAll e $ liftM return a
setAttr :: SetAttr m elem => elem -> GenAttribute m -> GenXML m
setAll :: SetAttr m elem => elem -> GenAttributeList m -> GenXML m

-- | prepend <tt>attr</tt> to the list of attributes for the <tt>elem</tt>
(<@) :: (SetAttr m elem, EmbedAsAttr m attr) => elem -> attr -> GenXML m

-- | prepend <tt>attr</tt> to the list of attributes for the <tt>elem</tt>
set :: (SetAttr m elem, EmbedAsAttr m attr) => elem -> attr -> GenXML m

-- | prepend the list of <tt>attr</tt> to the attributes for the
--   <tt>elem</tt>
(<<@) :: (SetAttr m elem, EmbedAsAttr m attr) => elem -> [attr] -> GenXML m
class XMLGen m => AppendChild m elem where appChild e c = appAll e $ liftM return c
appChild :: AppendChild m elem => elem -> GenChild m -> GenXML m
appAll :: AppendChild m elem => elem -> GenChildList m -> GenXML m

-- | append child to the children of <tt>elem</tt>
(<:) :: (AppendChild m elem, EmbedAsChild m c) => elem -> c -> GenXML m

-- | append child to the children of <tt>elem</tt>
app :: (AppendChild m elem, EmbedAsChild m c) => elem -> c -> GenXML m

-- | append children to the children of <tt>elem</tt>
(<<:) :: (AppendChild m elem, EmbedAsChild m c) => elem -> [c] -> GenXML m

-- | Names can be simple or qualified with a domain. We want to
--   conveniently use both simple strings or pairs wherever a <a>Name</a>
--   is expected.
class Show n => IsName n s
toName :: IsName n s => n -> Name s
class TypeCast a b | a -> b, b -> a
typeCast :: TypeCast a b => a -> b
class TypeCast' t a b | t a -> b, t b -> a
typeCast' :: TypeCast' t a b => t -> a -> b
class TypeCast'' t a b | t a -> b, t b -> a
typeCast'' :: TypeCast'' t a b => t -> a -> b
class TypeCastM ma mb | ma -> mb, mb -> ma
typeCastM :: TypeCastM ma mb => ma x -> mb x
class TypeCastM' t ma mb | t ma -> mb, t mb -> ma
typeCastM' :: TypeCastM' t ma mb => t -> ma x -> mb x
class TypeCastM'' t ma mb | t ma -> mb, t mb -> ma
typeCastM'' :: TypeCastM'' t ma mb => t -> ma x -> mb x
instance [overlap ok] Applicative m => Applicative (XMLGenT m)
instance [overlap ok] Alternative m => Alternative (XMLGenT m)
instance [overlap ok] Monad m => Monad (XMLGenT m)
instance [overlap ok] Functor m => Functor (XMLGenT m)
instance [overlap ok] MonadIO m => MonadIO (XMLGenT m)
instance [overlap ok] MonadPlus m => MonadPlus (XMLGenT m)
instance [overlap ok] MonadWriter w m => MonadWriter w (XMLGenT m)
instance [overlap ok] MonadReader r m => MonadReader r (XMLGenT m)
instance [overlap ok] MonadState s m => MonadState s (XMLGenT m)
instance [overlap ok] MonadRWS r w s m => MonadRWS r w s (XMLGenT m)
instance [overlap ok] MonadCont m => MonadCont (XMLGenT m)
instance [overlap ok] MonadError e m => MonadError e (XMLGenT m)
instance [overlap ok] (Show n, Show a) => Show (Attr n a)
instance [overlap ok] TypeCastM'' () ma ma
instance [overlap ok] TypeCastM'' t ma mb => TypeCastM' t ma mb
instance [overlap ok] TypeCastM' () ma mb => TypeCastM ma mb
instance [overlap ok] TypeCast'' () a a
instance [overlap ok] TypeCast'' t a b => TypeCast' t a b
instance [overlap ok] TypeCast' () a b => TypeCast a b
instance [overlap ok] IsName (Text, Text) Text
instance [overlap ok] IsName Text Text
instance [overlap ok] IsName (String, String) Text
instance [overlap ok] Show a => IsName (Name a) a
instance [overlap ok] IsName String Text
instance [overlap ok] IsName String String
instance [overlap ok] (AppendChild m x, TypeCastM m1 m) => AppendChild m (XMLGenT m1 x)
instance [overlap ok] (TypeCastM m1 m, SetAttr m x) => SetAttr m (XMLGenT m1 x)
instance [overlap ok] EmbedAsAttr m a => EmbedAsAttr m [a]
instance [overlap ok] XMLGen m => EmbedAsAttr m (AttributeType m)
instance [overlap ok] (EmbedAsAttr m (Attr a v), TypeCastM m1 m) => EmbedAsAttr m (Attr a (XMLGenT m1 v))
instance [overlap ok] (XMLGen m, EmbedAsAttr m a) => EmbedAsAttr m (XMLGenT m a)
instance [overlap ok] XMLGen m => EmbedAsChild m ()
instance [overlap ok] (XMLGen m, XMLType m ~ x) => EmbedAsChild m x
instance [overlap ok] XMLGen m => EmbedAsChild m (ChildType m)
instance [overlap ok] EmbedAsChild m c => EmbedAsChild m [c]
instance [overlap ok] (EmbedAsChild m c, m ~ n) => EmbedAsChild m (XMLGenT n c)
instance [overlap ok] MonadTrans XMLGenT

module HSP.Monad
newtype HSPT xml m a
HSPT :: m a -> HSPT xml m a
unHSPT :: HSPT xml m a -> m a
instance [overlap ok] Functor m => Functor (HSPT xml m)
instance [overlap ok] Applicative m => Applicative (HSPT xml m)
instance [overlap ok] Alternative m => Alternative (HSPT xml m)
instance [overlap ok] Monad m => Monad (HSPT xml m)
instance [overlap ok] MonadPlus m => MonadPlus (HSPT xml m)
instance [overlap ok] MonadIO m => MonadIO (HSPT xml m)
instance [overlap ok] MonadReader r m => MonadReader r (HSPT xml m)
instance [overlap ok] MonadWriter w m => MonadWriter w (HSPT xml m)
instance [overlap ok] MonadState s m => MonadState s (HSPT xml m)
instance [overlap ok] MonadCont m => MonadCont (HSPT xml m)
instance [overlap ok] MonadError e m => MonadError e (HSPT xml m)
instance [overlap ok] MonadFix m => MonadFix (HSPT xml m)
instance [overlap ok] (Functor m, Monad m) => XMLGenerator (HSPT XML m)
instance [overlap ok] (Functor m, Monad m) => EmbedAsAttr (HSPT XML m) (Attr Text Int)
instance [overlap ok] (Functor m, Monad m) => EmbedAsAttr (HSPT XML m) (Attr Text Bool)
instance [overlap ok] (Monad m, Functor m) => EmbedAsAttr (HSPT XML m) (Attr Text Char)
instance [overlap ok] (Functor m, Monad m) => EmbedAsAttr (HSPT XML m) (Attr Text Text)
instance [overlap ok] (Monad m, Functor m) => EmbedAsAttr (HSPT XML m) Attribute
instance [overlap ok] (Functor m, Monad m) => EmbedAsChild (HSPT XML m) ()
instance [overlap ok] (Functor m, Monad m) => EmbedAsChild (HSPT XML m) Char
instance [overlap ok] (Functor m, Monad m) => EmbedAsChild (HSPT XML m) Text
instance [overlap ok] (Functor m, Monad m) => EmbedAsChild (HSPT XML m) String
instance [overlap ok] (Functor m, Monad m) => EmbedAsChild (HSPT XML m) [XML]
instance [overlap ok] (Functor m, Monad m) => EmbedAsChild (HSPT XML m) XML
instance [overlap ok] (Functor m, Monad m) => AppendChild (HSPT XML m) XML
instance [overlap ok] (Functor m, Monad m) => SetAttr (HSPT XML m) XML
instance [overlap ok] (Functor m, Monad m) => XMLGen (HSPT XML m)
instance [overlap ok] MonadTrans (HSPT xml)

module HSP