| hxt-8.5.4: A collection of tools for processing XML with Haskell. | Source code | Contents | Index
Text.XML.HXT.Arrow.Pickle.Xml |
Portability | portable
Stability | experimental
Maintainer | Uwe Schmidt (uwe@fh-wedel.de)
Description
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)
Synopsis
data St = St {
attributes :: [XmlTree]
contents :: [XmlTree]
}
data PU a = PU {
appPickle :: (a, St) -> St
appUnPickle :: St -> (Maybe a, St)
theSchema :: Schema
}
emptySt :: St
addAtt :: XmlTree -> St -> St
addCont :: XmlTree -> St -> St
dropCont :: St -> St
getAtt :: QName -> St -> Maybe XmlTree
getCont :: St -> Maybe XmlTree
pickleDoc :: PU a -> a -> XmlTree
unpickleDoc :: PU a -> XmlTree -> Maybe a
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
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)
xp6Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU (a, b, c, d, e, f)
xpText :: PU String
xpTextDT :: Schema -> PU String
xpText0 :: PU String
xpText0DT :: Schema -> PU String
xpPrim :: (Read a, Show a) => PU a
xpTree :: PU XmlTree
xpTrees :: PU [XmlTree]
xpXmlText :: PU String
xpOption :: PU a -> PU (Maybe a)
xpDefault :: Eq a => a -> PU a -> PU a
xpList :: PU a -> PU [a]
xpList1 :: PU a -> PU [a]
xpMap :: Ord k => String -> String -> PU k -> PU v -> PU (Map k v)
xpAlt :: (a -> Int) -> [PU a] -> PU a
xpElemQN :: QName -> PU a -> PU a
xpElem :: String -> PU a -> PU a
xpElemWithAttrValue :: String -> String -> String -> PU a -> PU a
xpAttrQN :: QName -> PU a -> PU a
xpAttr :: String -> PU a -> PU a
xpAttrImplied :: String -> PU a -> PU (Maybe a)
xpAttrFixed :: String -> String -> PU ()
xpAddFixedAttr :: String -> String -> PU a -> PU a
class XmlPickler a where
xpickle :: PU a
Documentation
data St | Source
Constructors
St |
attributes :: [XmlTree] |
contents :: [XmlTree] |
data PU a | Source
Constructors
PU |
appPickle :: (a, St) -> St |
appUnPickle :: St -> (Maybe a, St) |
theSchema :: Schema |
emptySt :: St | Source
addAtt :: XmlTree -> St -> St | Source
addCont :: XmlTree -> St -> St | Source
dropCont :: St -> St | Source
getAtt :: QName -> St -> Maybe XmlTree | Source
getCont :: St -> Maybe XmlTree | Source
pickleDoc :: PU a -> a -> XmlTree | Source
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
unpickleDoc :: PU a -> XmlTree -> Maybe a | Source
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
xpZero :: PU a | Source
The zero pickler Encodes nothing, fails always during unpickling
xpUnit :: PU () | Source
xpLift :: a -> PU a | Source
Lift a value to a pickler When pickling, nothing is encoded, when unpickling, the given value is inserted. This pickler always succeeds.
xpLiftMaybe :: Maybe a -> PU a | Source
Lift a Maybe value to a pickler. `Nothing` is mapped to the zero pickler, `Just x` is pickled with `xpLift x`.
xpCondSeq :: PU b -> (b -> a) -> PU a -> (a -> PU b) -> PU b | Source
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` . The schema must be attached later, e.g. in xpPair or other higher level combinators
xpSeq :: (b -> a) -> PU a -> (a -> PU b) -> PU b | Source
Combine two picklers sequentially. If the first fails during unpickling, the whole unpickler fails
xpChoice :: PU b -> PU a -> (a -> PU b) -> PU b | Source
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 is only used as combinator for unpickling.
xpWrap :: (a -> b, b -> a) -> PU a -> PU b | Source
map value into another domain and apply pickler there One of the most often used picklers.
xpWrapMaybe :: (a -> Maybe b, b -> a) -> PU a -> PU b | Source
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
xpPair :: PU a -> PU b -> PU (a, b) | Source
pickle a pair of values sequentially Used for pairs or together with wrap for pickling algebraic data types with two components
xpTriple :: PU a -> PU b -> PU c -> PU (a, b, c) | Source
Like `xpPair` but for triples
xp4Tuple :: PU a -> PU b -> PU c -> PU d -> PU (a, b, c, d) | Source
Like `xpPair` and `xpTriple` but for 4-tuples
xp5Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU (a, b, c, d, e) | Source
Like `xpPair` and `xpTriple` but for 5-tuples
xp6Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU (a, b, c, d, e, f) | Source
Like `xpPair` and `xpTriple` but for 6-tuples
xpText :: PU String | Source
Pickle a string into an XML text node One of the most often used primitive picklers. Attention: For pickling empty strings use `xpText0`. If the text has a more specific datatype than xsd:string, use `xpTextDT`
xpTextDT :: Schema -> PU String | Source
Pickle a string into an XML text node Text pickler with a description of the structure of the text by a schema. A schema for a data type can be defined by `scDT`. In Text.XML.HXT.Arrow.Pickle.Schema there are some more functions for creating simple datatype descriptions.
xpText0 :: PU String | Source
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.
xpText0DT :: Schema -> PU String | Source
Pickle a possibly empty string with a datatype description into an XML node. Like `xpText0` but with extra Parameter for datatype description as in `xpTextDT`.
xpPrim :: (Read a, Show a) => PU a | Source
Pickle an arbitrary value by applyling show during pickling and read during unpickling. Real pickling is then done with `xpText`. One of the most often used pimitive picklers. Applicable for all types which are instances of `Read` and `Show`
xpTree :: PU XmlTree | Source
Pickle an XmlTree by just adding it Usefull for components of type XmlTree in other data structures
xpTrees :: PU [XmlTree] | Source
Pickle a whole list of XmlTrees by just adding the list, unpickle is done by taking all element contents. This pickler should always be combined with `xpElem` for taking the whole contents of an element.
xpXmlText :: PU String | Source
Pickle a string representing XML contents by inserting the tree representation into the XML document. Unpickling is done by converting the contents with `xshowEscapeXml` into a string, this function will escape all XML special chars, such that pickling the value back becomes save. Pickling is done with `xread`
xpOption :: PU a -> PU (Maybe a) | Source
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
xpDefault :: Eq a => a -> PU a -> PU a | Source
Optional conversion with default value The default value is not encoded in the XML document, during unpickling the default value is inserted if the pickler fails
xpList :: PU a -> PU [a] | Source
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 combination with `xpWrap` for constructing set and map picklers
xpList1 :: PU a -> PU [a] | Source
Encoding of a none empty list of values Attention: when calling this pickler with an empty list, an internal error "head of empty list is raised".
xpMap :: Ord k => String -> String -> PU k -> PU v -> PU (Map k v) | Source
Standard pickler for maps This pickler converts a map into a list of pairs. All key value pairs are mapped to an element with name (1.arg), the key is encoded as an attribute named by the 2. argument, the 3. arg is the pickler for the keys, the last one for the values
xpAlt :: (a -> Int) -> [PU a] -> PU a | Source
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
xpElemQN :: QName -> PU a -> PU a | Source
Pickler for wrapping/unwrapping data into an XML element Extra parameter is the element name given as a QName. THE pickler for constructing nested structures Example:
     xpElemQN (mkName "number") $ xpickle
will map an (42::Int) onto
     <number>42</number>
xpElem :: String -> PU a -> PU a | Source
convenient Pickler for xpElemQN
     xpElem n = xpElemQN (mkName n)
xpElemWithAttrValue :: String -> String -> String -> PU a -> PU a | Source
Pickler for wrapping/unwrapping data into an XML element with an attribute with given value To make XML structures flexible but limit the number of different elements, it's sometimes useful to use a kind of generic element with a key value structure Example:
     <attr name="key1">value1</attr>
     <attr name="key2">value2</attr>
     <attr name="key3">value3</attr>
the Haskell datatype may look like this
     type T = T { key1 :: Int ; key2 :: String ; key3 :: Double }
Then the picker for that type looks like this
     xpT :: PU T
     xpT = xpWrap ( uncurry3 T, \ t -> (key1 t, key2 t, key3 t) ) $
           xpTriple (xpElemWithAttrValue "attr" "name" "key1" $ xpickle)
                    (xpElemWithAttrValue "attr" "name" "key2" $ xpText0)
                    (xpElemWithAttrValue "attr" "name" "key3" $ xpickle)
xpAttrQN :: QName -> PU a -> PU a | Source
Pickler for storing/retreiving data into/from an attribute value The attribute is inserted in the surrounding element constructed by the `xpElem` pickler
xpAttr :: String -> PU a -> PU a | Source
convenient Pickler for xpAttrQN
     xpAttr n = xpAttrQN (mkName n)
xpAttrImplied :: String -> PU a -> PU (Maybe a) | Source
Add an optional attribute for an optional value (Maybe a).
xpAttrFixed :: String -> String -> PU () | Source
xpAddFixedAttr :: String -> String -> PU a -> PU a | Source
Add an attribute with a fixed value. Useful e.g. to declare namespaces. Is implemented by `xpAttrFixed`
class XmlPickler a where | Source
The class for overloading `xpickle`, the default pickler
Methods
xpickle :: PU a | Source
Instances
XmlPickler Int
XmlPickler Integer
XmlPickler ()
XmlPickler a => XmlPickler ([] a)
XmlPickler a => XmlPickler (Maybe a)
(XmlPickler a, XmlPickler b) => XmlPickler ((,) a b)
(XmlPickler a, XmlPickler b, XmlPickler c) => XmlPickler ((,,) a b c)
(XmlPickler a, XmlPickler b, XmlPickler c, XmlPickler d) => XmlPickler ((,,,) a b c d)
(XmlPickler a, XmlPickler b, XmlPickler c, XmlPickler d, XmlPickler e) => XmlPickler ((,,,,) a b c d e)
Produced by Haddock version 2.4.2