 | Haskell Xml Toolbox 7.3: The complete API | Source code | Contents | Index |
| Text.XML.HXT.Arrow.XmlPickle |
|
Version : $Id$
Pickler functions for converting between user defined data types and XmlTree data. Usefull for persistent storage and retreival of arbitray data as XML documents
This module is an adaptation of the pickler combinators developed by Andrew Kennedy ( http://research.microsoft.com/~akenn/fun/picklercombinators.pdf )
The difference to Kennedys approach is that the target is not a list of Chars but a list of XmlTrees. The basic picklers will convert data into XML text nodes. New are the picklers for creating elements and attributes.
One extension was neccessary: The unpickling may fail. Therefore the unpickler has a Maybe result type. Failure is used to unpickle optional elements (Maybe data) and lists of arbitray length
There is an example program demonstrating the use of the picklers for a none trivial data structure. (see "examples/arrows/pickle" directory)
data PU a = PU {
| ||
| xpZero :: PU a | ||
| xpUnit :: PU () | ||
| xpLift :: a -> PU a | ||
| xpLiftMaybe :: Maybe a -> PU a | ||
| xpCondSeq :: PU b -> (b -> a) -> PU a -> (a -> PU b) -> PU b | ||
| xpSeq :: (b -> a) -> PU a -> (a -> PU b) -> PU b | ||
| xpList :: PU a -> PU [a] | ||
| xpText :: PU String | ||
| xpText0 :: PU String | ||
| xpPrim :: (Read a, Show a) => PU a | ||
| xpChoice :: PU b -> PU a -> (a -> PU b) -> PU b | ||
| xpWrap :: (a -> b, b -> a) -> PU a -> PU b | ||
| xpWrapMaybe :: (a -> Maybe b, b -> a) -> PU a -> PU b | ||
| xpPair :: PU a -> PU b -> PU (a, b) | ||
| xpTriple :: PU a -> PU b -> PU c -> PU (a, b, c) | ||
| xp4Tuple :: PU a -> PU b -> PU c -> PU d -> PU (a, b, c, d) | ||
| xp5Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU (a, b, c, d, e) | ||
| xpOption :: PU a -> PU (Maybe a) | ||
| xpAlt :: (a -> Int) -> [PU a] -> PU a | ||
| xpElem :: String -> PU a -> PU a | ||
| xpAttr :: String -> PU a -> PU a | ||
| xpTree :: PU XmlTree | ||
| pickleDoc :: PU a -> a -> XmlTree | ||
| unpickleDoc :: PU a -> XmlTree -> Maybe a | ||
| class XmlPickler a where | ||
| ||
| xpickle :: XmlPickler a => PU a | ||
| xpickleDocument :: PU a -> Attributes -> String -> IOStateArrow s a XmlTree | ||
| xunpickleDocument :: PU a -> Attributes -> String -> IOStateArrow s b a |
| Constructors | ||||||||
| ||||||||
The zero pickler
Encodes othing, fails always during unpickling
Lift a value to a pickler
When pickling, nothing is encoded, when unpickling, the given value is inserted. This pickler always succeeds.
Lift a Maybe value to a pickler.
Nothing is mapped to the zero pickler, Just x is pickled with xpLift x.
pickle/unpickle combinator for sequence and choice.
When the first unpickler fails, the second one is taken, else the third one configured with the result from the first is taken. This pickler is a generalisation for xpSeq and xpChoice .
Combine two picklers sequentially.
If the first fails during unpickling, the whole unpickler fails
Encoding of list values by pickling all list elements sequentially.
Unpickler relies on failure for detecting the end of the list. The standard pickler for lists. Can also be used in compination with xpWrap for constructing set and map picklers
Pickle a string into an XML text node
One of the most often used primitive picklers. Attention: For pickling empty strings use xpText0.
Pickle a possibly empty string into an XML node.
Must be used in all places, where empty strings are legal values. If the content of an element can be an empty string, this string disapears during storing the DOM into a document and reparse the document. So the empty text node becomes nothing, and the pickler must deliver an empty string, if there is no text node in the document.
Pickle an arbitrary value by applyling show during pickling and read during unpickling.
Real pickling is then done with xpString. One of the most often used pimitive picklers. Applicable for all types which are instances of Read and Show
combine tow picklers with a choice
Run two picklers in sequence like with xpSeq. When during unpickling the first one fails, an alternative pickler (first argument) is applied. This pickler only is used as combinator for unpickling.
map value into another domain and apply pickler there
One of the most often used picklers.
like xpWrap, but if the inverse mapping is undefined, the unpickler fails
Map a value into another domain. If the inverse mapping is undefined (Nothing), the unpickler fails
pickle a pair of values sequentially
Used for pairs or together with wrap for pickling algebraic data types with two components
Encoding of optional data by ignoring the Nothing case during pickling and relying on failure during unpickling to recompute the Nothing case
The default pickler for Maybe types
Pickler for sum data types.
Every constructor is mapped to an index into the list of picklers. The index is used only during pickling, not during unpickling, there the 1. match is taken
Pickler for wrapping/unwrapping data into an XML element
Extra parameter is the element name. THE pickler for constructing nested structures
Pickler for storing/retreiving data into/from an attribute value
The attribute is inserted in the surrounding element constructed by the xpElem pickler
Pickle an XmlTree by just adding it
Usefull for components of type XmlTree in other data structures
conversion of an arbitrary value into an XML document tree.
The pickler, first parameter, controls the conversion process. Result is a complete document tree including a root node
Conversion of an XML document tree into an arbitrary data type
The inverse of pickleDoc. This law should hold for all picklers: unpickle px . pickle px $ v == Just v . Not every possible combination of picklers make sense. For reconverting a value from an XML tree, is becomes neccessary, to introduce "enough" markup for unpickling the value
| The class for overloading xpickle, the default pickler | |||||||||
| Methods | |||||||||
| |||||||||
 Instances | |||||||||
|
store an arbitray value in a persistent XML document
The pickler converts a value into an XML tree, this is written out with writeDocument. The option list is passed to writeDocument
read an arbitray value from an XML document
The document is read with readDocument. Options are passed to readDocument. The conversion from XmlTree is done with the pickler.
xpickleDocument xp al dest >>> xunpickleDocument xp al' dest is the identity arrow when applied with the appropriate options. When during pickling indentation is switched on, the whitespace must be removed during unpickling.