## XmlContent

Text.XML.HaXml.XmlContent is a library/class for translating Haskell data from any program into a valid XML document (and back again). In principle, it gives an alternative to the standard Read and Show classes, allowing you to use fully typed data in Haskell rather than the generic XML tree representation.

Usage 1. It works rather like the existing Read and Show classes: you must create an instance of the XmlContent class for every datatype you wish to use for I/O. However, because this class is not a standard one, no Haskell compilers support the `deriving` clause for it yet. Fear not! There is a pre-processor tool called DrIFT which derives class instances automatically. We have extended DrIFT's ruleset to include the XmlContent class.

(Please note that DrIFT is sometimes a bit fragile when parsing Haskell sources - it occasionally fails to recognise the derive command. We have found a workaround: isolate just the `data` type declarations that are of interest, and run DrIFT on them separately.) The syntax required is like this example:

      data MyType a = A a | B String deriving (Eq, Show)
          {-! derive : XmlContent !-}	-- this line is for DrIFT

Usage 2. Alternatively, you may start by having XML documents with a standard DTD defined elsewhere, e.g. SVG, SMIL, MathML etc. You can convert the DTD into an isomorphic collection of Haskell datatypes, including all the requisite instances of XmlContent, with the tool DtdToHaskell included in HaXml.

API To read and write Haskell data values as XML files, you have a choice of function pairs: `toXML/fromXML` convert between typed Haskell values and the generic internal XML representation; `showXml/readXml` convert to/from Strings; `fWriteXml/fReadXml` convert to/from named files; `hPutXml/hGetXml` convert to/from file Handles.

        toXml     :: XmlContent a => Bool -> a  -> Document ()
        fromXml   :: XmlContent a => Document Posn -> Either String a

        readXml   :: XmlContent a => String        -> Either String a
        showXml   :: XmlContent a => Bool -> a  -> String

        fReadXml  :: XmlContent a => FilePath -> IO a
        fWriteXml :: XmlContent a => FilePath -> a -> IO ()

        hGetXml   :: XmlContent a => Handle   -> IO a
        hPutXml   :: XmlContent a => Handle   -> Bool -> a -> IO ()

Because parsing the document might fail, some of these functions return an Either String, where the string contains an error message. Boolean arguments to output-writing functions indicate whether or not to include a DTD in the output.

Particularly when you read from XML, you may need to resolve the overloading of the result value in one of the usual ways (e.g. by implicit context at point of use, by explicit type signatures on values, use value as an argument to a function with an explicit signature, use ``asTypeOf``, etc.)