-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Reading/writing Haskell data from/to XML -- -- A library for readingwriting Haskell data fromto XML. Only -- prerequisite is that the data type derives Generic. @package tofromxml @version 0.1.0.0 -- | In order to write a Haskell value to an XML file, the value's type -- just has to be an instance of Generic (usually one would use -- the deriving Generic clause in the data -- defintion). Then, the writeToXMLFile will write an XML file -- representing the value. This value can be read again using -- readFromXMLFile. See the following example (pragma syntax below -- is broken, how can one correctly incorporate comments in a haddock -- code block?): -- -- 
--   { -# LANGUAGE DeriveGeneric #- }
--   { -# OPTIONS_GHC -fcontext-stack=50 #- }
--   
--   import Text.XML.ToFromXML
--   -- GHC.Generics is exported by ToFromXML
--   
--   data Test = Test { str::String, something::(Int,Char) }
--   	deriving (Generic,Show,Eq)
--   
--   main = do
--   	let test = Test "abc" (42,'z')
--   	writeToXMLFile "test.xml" test
--   	putStrLn $ "writeToXMLFile : " ++ show test
--   
--   	-- readFromXMLFile's return type can be inferred in this example,
--   	-- otherwise it would have to be declared
--   	test' <- readFromXMLFile "test.xml"
--   	putStrLn $ "readFromXMLFile: " ++ show test'
--   	
--   	putStrLn $ if test==test' then "OK." else "ERROR!"
--
-- -- Remark: Both writeToXMLFile and readFromXMLFile require -- the value type a's generic represention Rep a be an -- instance of GFromToXML, but this is automatically fulfilled. -- -- The generated XML file is -- -- 
--   <?xml version="1.0" encoding="UTF-8"?>
--   <CONSTRUCTOR name="Test">
--     <ARG-1 selector="str">abc</ARG-1>
--     <ARG-2 selector="something">
--       <PAIR>
--         <FIRST>42</FIRST>
--         <SECOND>z</SECOND>
--       </PAIR>
--     </ARG-2>
--   </CONSTRUCTOR>
--
-- -- The general intention of this module is to keep the generated XML as -- intuitive and easy to read as possible. For example, we do flatten -- nested pairs used by GHC.Generics to represent n-tuples, and -- TABs and CRs are used to encode long text, so it keeps its formatting -- (unfortunately, CDATA sections are not supported with the Node types -- used in Text.XML.Expat.Pickle). -- -- One might need to increase the context stack size with the -- -fcontext-stack option when compiling code using this module. -- -- A test suite is included in the package, see TestToFromXML.hs -- in the package's test directory. module Text.XML.ToFromXML -- | The class ToFromXML declares that there is a pickler for the -- instance type wrapped by the generic representation's K1 -- constructor. There are instances for data types that we do want to -- encode in more precise way, not following the generic pattern. For -- example, we want to encode unit () as a distinct tag -- <UNIT/>, not as text content generated with show/read. -- We give a default signature and definition which we can use -- conveniently by just stating instance ToFromXML Word32 for -- numeric types, for example. -- -- Special chars are represented in XML by Haskell's escape sequences. A -- char is not embraced by single quotes in the tag content (as it would -- be using the default instance). -- -- Since unfortunately CDATA sections are not supported with the Node -- types used in Text.XML.Expat.Pickle we are relying on, a String -- has to be represented in XML as a tag's text content, using the common -- Haskell escape sequences. For better readability and prevention of -- very long lines in the XML file, after each '\r', -- '\n' and '\t' the same character is inserted -- unescaped after the character's escape sequence. The unescaped -- character is removed again when parsing the String. For example, -- "abcndef" will be written in the XML file as -- "abc\nndef", with the LF escaped (i.e. "\n") and -- followed by a real LF ('\n'). Injecting line breaks and tabs -- makes long text much more readable und editable by humans (which is -- one of the original purposes of XML). The real LF will be filtered out -- again while parsing the XML file String. class ToFromXML a where xMLPickler = xpContent xpPrim xMLPickler :: ToFromXML a => Pickler a -- | Converts generic Haskell data to a (strict) ByteString -- containing the XML representation. In most cases, the data type would -- probably be deriving Generic using the -- DeriveGeneric language pragma. toXML :: (Generic a, GToFromXML (Rep a)) => a -> ByteString -- | Convenience function wrapping around fromXMLEither, throwing an -- error in case of a parsing error. fromXML :: (Generic a, GToFromXML (Rep a)) => ByteString -> a -- | Construct generic Haskell data from a (strict) ByteString -- containing the XML representation. fromXMLEither will return -- Left in case of a XMLParseError, Right otherwise. fromXMLEither :: GToFromXML f => ByteString -> Either String (f p) -- | Action reading generic Haskell data from an XML file. The underlying -- readFile operation is strict. readFromXMLFile :: (Generic a, GToFromXML (Rep a)) => FilePath -> IO a -- | Action writing an XML representation of generic Haskell data to a -- file. The underlying writeFile operation is strict. writeToXMLFile :: (Generic a, GToFromXML (Rep a)) => FilePath -> a -> IO () instance [overlap ok] (Generic a, GToFromXML (Rep a)) => ToFromXML a instance [overlap ok] (Ix i, Show i, Read i, ToFromXML e) => ToFromXML (Array i e) instance [overlap ok] (ToFromXML a, Ord a) => ToFromXML (Set a) instance [overlap ok] (ToFromXML a, ToFromXML b) => ToFromXML (Either a b) instance [overlap ok] ToFromXML a => ToFromXML (Maybe a) instance [overlap ok] (ToFromXML a, ToFromXML b, ToFromXML c, ToFromXML d, ToFromXML e, ToFromXML f) => ToFromXML (a, b, c, d, e, f) instance [overlap ok] (ToFromXML a, ToFromXML b, ToFromXML c, ToFromXML d, ToFromXML e) => ToFromXML (a, b, c, d, e) instance [overlap ok] (ToFromXML a, ToFromXML b, ToFromXML c, ToFromXML d) => ToFromXML (a, b, c, d) instance [overlap ok] (ToFromXML a, ToFromXML b, ToFromXML c) => ToFromXML (a, b, c) instance [overlap ok] (ToFromXML a, ToFromXML b) => ToFromXML (a, b) instance [overlap ok] ToFromXML v => ToFromXML (IntMap v) instance [overlap ok] (Ord k, ToFromXML k, ToFromXML v) => ToFromXML (Map k v) instance [overlap ok] ToFromXML String instance [overlap ok] ToFromXML Char instance [overlap ok] ToFromXML Bool instance [overlap ok] (Show a, Read a) => ToFromXML (Complex a) instance [overlap ok] (Show a, Read a, Integral a) => ToFromXML (Ratio a) instance [overlap ok] ToFromXML Double instance [overlap ok] ToFromXML Float instance [overlap ok] ToFromXML Word64 instance [overlap ok] ToFromXML Word32 instance [overlap ok] ToFromXML Word16 instance [overlap ok] ToFromXML Word8 instance [overlap ok] ToFromXML Word instance [overlap ok] ToFromXML Integer instance [overlap ok] ToFromXML Int64 instance [overlap ok] ToFromXML Int32 instance [overlap ok] ToFromXML Int16 instance [overlap ok] ToFromXML Int8 instance [overlap ok] ToFromXML Int instance [overlap ok] ToFromXML a => ToFromXML [a] instance [overlap ok] ToFromXML () instance [overlap ok] ToFromXML a => GToFromXML (K1 R a) instance [overlap ok] GToFromXML U1 instance [overlap ok] (GToFromXML f, Selector s) => GToFromXML (M1 S s f) instance [overlap ok] GToFromXML f => GToFromXML (M1 S NoSelector f) instance [overlap ok] (GToFromXML f, Constructor c) => GToFromXML (M1 C c f) instance [overlap ok] (GToFromXML f, Datatype d) => GToFromXML (M1 D d f) instance [overlap ok] (GToFromXML f1, GToFromXML f2) => GToFromXML (f1 :+: f2) instance [overlap ok] PickleProdN (f1 :*: f2) => GToFromXML (f1 :*: f2) instance [overlap ok] (GToFromXML f, Selector s) => PickleProdN (M1 S s f) instance [overlap ok] GToFromXML f => PickleProdN (M1 S NoSelector f) instance [overlap ok] (PickleProdN f1, PickleProdN f2) => PickleProdN (f1 :*: f2)