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


-- | Fast XML generation library
--   
--   Library for high-performance XML generation.
@package xmlgen
@version 0.4.0.2


-- | This module provides combinators for generating XML documents.
--   
--   As an example, suppose you want to generate the following XML
--   document:
--   
--   <pre>
--   &lt;?xml version="1.0"?&gt;
--   &lt;people&gt;
--     &lt;person age="32"&gt;Stefan&lt;/person&gt;
--     &lt;person age="4"&gt;Judith&lt;/person&gt;
--   &lt;/people&gt;
--   </pre>
--   
--   Then you could use the following Haskell code:
--   
--   <pre>
--   let people = [("Stefan", "32"), ("Judith", "4")]
--   in <a>doc</a> <a>defaultDocInfo</a> $
--        <a>xelem</a> "people" $
--          <a>xelems</a> $ map ((name, age) -&gt; <a>xelem</a> "person" (<a>xattr</a> "age" age <a>&lt;#&gt;</a> <a>xtext</a> name)) people
--   </pre>
module Text.XML.Generator

-- | The type <tt>Xml t</tt> represent a piece of XML of type <tt>t</tt>,
--   where <tt>t</tt> is usually one of <a>Elem</a>, <a>Attr</a>, or
--   <a>Doc</a>.
data Xml t

-- | A piece of XML at the document level.
data Doc

-- | The <a>DocInfo</a> type contains all information of an XML document
--   except the root element.
data DocInfo
DocInfo :: Bool -> Maybe String -> Xml Doc -> Xml Doc -> DocInfo

-- | Value of the <tt>standalone</tt> attribute in the <tt>&lt;?xml ...
--   ?&gt;</tt> header
docInfo_standalone :: DocInfo -> Bool

-- | Document type (N.B.: rendering does not escape this value)
docInfo_docType :: DocInfo -> Maybe String

-- | Content before the root element
docInfo_preMisc :: DocInfo -> Xml Doc

-- | Content after the root element
docInfo_postMisc :: DocInfo -> Xml Doc

-- | Constructs an XML document from a <a>DocInfo</a> value and the root
--   element.
doc :: DocInfo -> Xml Elem -> Xml Doc

-- | The default document info (standalone, without document type, without
--   content before/after the root element).
defaultDocInfo :: DocInfo

-- | Type for representing presence or absence of an XML namespace.
data Namespace

-- | Namespace prefix.
type Prefix = String

-- | Namespace URI.
type Uri = String

-- | Constructs a qualified XML namespace. The given URI must not be the
--   empty string.
namespace :: Prefix -> Uri -> Namespace

-- | A <a>Namespace</a> value denoting the absence of any XML namespace
--   information.
noNamespace :: Namespace

-- | A <a>Namespace</a> value denoting the default namespace.
--   
--   <ul>
--   <li>For elements, this is the namespace currently mapped to the empty
--   prefix.</li>
--   <li>For attributes, the default namespace does not carry any namespace
--   information.</li>
--   </ul>
defaultNamespace :: Namespace

-- | A piece of XML at the element level.
data Elem

-- | Class providing methods for constructing XML elements.
--   
--   The <a>String</a> instance of this class constructs an element in the
--   default namespace, the <a>Namespace</a> instance allows customization
--   of namespaces.
class AddChildren c => MkElem n c
xelem :: MkElem n c => n -> MkElemRes n c

-- | Class providing a method for constructing XML elements without
--   children.
--   
--   The <a>String</a> instance of this class constructs an element in the
--   default namespace, the <a>Namespace</a> instance allows customization
--   of namespaces.
class MkEmptyElem n
xelemEmpty :: MkEmptyElem n => n -> MkEmptyElemRes n

-- | Class for adding children to an element.
--   
--   The various instances of this class allow the addition of different
--   kinds of children.
class AddChildren c

-- | Merges a list of elements into a single piece of XML at the element
--   level.
xelems :: [Xml Elem] -> Xml Elem

-- | No elements at all.
noElems :: Xml Elem

-- | The expression <tt>xelemWithText n t</tt> constructs an XML element
--   with name <tt>n</tt> and text content <tt>t</tt>.
xelemWithText :: TextContent t => String -> t -> Xml Elem

-- | Shortcut for the <a>mappend</a> functions of monoids. Used to
--   concatenate elements, attributes and text nodes.
(<>) :: Monoid t => t -> t -> t

-- | Shortcut for coonstructing pairs. Used in combination with
--   <a>xelem</a> for separating child-attributes from child-elements.
(<#>) :: a -> b -> (a, b)

-- | A piece of XML at the attribute level.
data Attr

-- | Class providing methods for constructing XML attributes.
--   
--   The <a>String</a> instance of this class constructs an attribute with
--   a name in the default namespace, the <a>Namespace</a> instance allows
--   customization of namespaces.
class MkAttr n t
xattr :: (MkAttr n t, TextContent t) => n -> MkAttrRes n t
xattrRaw :: (MkAttr n t, RawTextContent t) => n -> MkAttrRes n t

-- | Merges a list of attributes into a single piece of XML at the
--   attribute level.
xattrs :: [Xml Attr] -> Xml Attr

-- | The empty attribute list.
noAttrs :: Xml Attr

-- | Construction of text content not subject to escaping.
class RawTextContent t

-- | Construction of text content subject to escaping.
class RawTextContent t => TextContent t

-- | Constructs a text node by escaping the given argument.
xtext :: TextContent t => t -> Xml Elem

-- | Constructs a text node <i>without</i> escaping the given argument.
xtextRaw :: RawTextContent t => t -> Xml Elem

-- | Constructs a reference to the named entity. <i>Note:</i> no escaping
--   is performed on the name of the entity
xentityRef :: String -> Xml Elem

-- | An empty, polymorphic piece of XML.
xempty :: Renderable t => Xml t

-- | Class providing methods for adding processing instructions and
--   comments.
class Renderable t => Misc t
xprocessingInstruction :: Misc t => String -> String -> Xml t
xcomment :: Misc t => String -> Xml t

-- | Renders a given piece of XML.
xrender :: (Renderable r, XmlOutput t) => Xml r -> t

-- | Instances of the <tt>XmlOutput</tt> class may serve as target of
--   serializing an XML document.
class XmlOutput t
fromBuilder :: XmlOutput t => Builder -> t

-- | Any type subject to rendering must implement this type class.
class Renderable t

-- | Document info for XHTML 1.0 frameset.
xhtmlFramesetDocInfo :: DocInfo

-- | Document info for XHTML 1.0 strict.
xhtmlStrictDocInfo :: DocInfo

-- | Document info for XHTML 1.0 transitional.
xhtmlTransitionalDocInfo :: DocInfo

-- | Constructs the root element of an XHTML document.
xhtmlRootElem :: String -> Xml Elem -> Xml Elem
instance [overlap ok] Show Namespace
instance [overlap ok] Eq Namespace
instance [overlap ok] Renderable Doc
instance [overlap ok] Renderable Attr
instance [overlap ok] Renderable Elem
instance [overlap ok] XmlOutput ByteString
instance [overlap ok] XmlOutput ByteString
instance [overlap ok] XmlOutput Builder
instance [overlap ok] Misc Doc
instance [overlap ok] Misc Elem
instance [overlap ok] Monoid (Xml Elem)
instance [overlap ok] MkEmptyElem Namespace
instance [overlap ok] MkEmptyElem String
instance [overlap ok] AddChildren c => MkElem Namespace c
instance [overlap ok] AddChildren c => MkElem String c
instance [overlap ok] AddChildren ()
instance [overlap ok] TextContent t => AddChildren t
instance [overlap ok] AddChildren (Xml Attr, Xml Elem)
instance [overlap ok] AddChildren (Xml Elem)
instance [overlap ok] AddChildren (Xml Attr)
instance [overlap ok] Monoid (Xml Attr)
instance [overlap ok] MkAttr Namespace t
instance [overlap ok] MkAttr String t
instance [overlap ok] RawTextContent ByteString
instance [overlap ok] RawTextContent ByteString
instance [overlap ok] TextContent Text
instance [overlap ok] RawTextContent Text
instance [overlap ok] TextContent Text
instance [overlap ok] RawTextContent Text
instance [overlap ok] TextContent String
instance [overlap ok] RawTextContent String