+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 => a -> Document + fromXml :: XmlContent a => Document -> a + + readXml :: XmlContent a => String -> Maybe a + showXml :: XmlContent a => a -> String + + fReadXml :: XmlContent a => FilePath -> IO a + fWriteXml :: XmlContent a => FilePath -> a -> IO () + + hGetXml :: XmlContent a => Handle -> IO a + hPutXml :: XmlContent a => Handle -> a -> IO () ++ +
+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.) + +