|
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 {} | | data PU a = PU {} | | 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 | | showPickled :: XmlPickler a => SysConfigList -> a -> String | | 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) | | xp7Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU (a, b, c, d, e, f, g) | | xp8Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU (a, b, c, d, e, f, g, h) | | xp9Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU (a, b, c, d, e, f, g, h, i) | | xp10Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU (a, b, c, d, e, f, g, h, i, j) | | xp11Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU (a, b, c, d, e, f, g, h, i, j, k) | | xp12Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU (a, b, c, d, e, f, g, h, i, j, k, l) | | xp13Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m) | | xp14Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n) | | xp15Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) | | xp16Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p) | | xp17Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q) | | xp18Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r) | | xp19Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s) | | xp20Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t) | | xp21Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU u -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u) | | xp22Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU u -> PU v -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v) | | xp23Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU u -> PU v -> PU w -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w) | | xp24Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU u -> PU v -> PU w -> PU x -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x) | | 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 | | xpTextAttr :: String -> PU String | | xpAttrImplied :: String -> PU a -> PU (Maybe a) | | xpAttrFixed :: String -> String -> PU () | | xpAddFixedAttr :: String -> String -> PU a -> PU a | | class XmlPickler a where | |
|
|
Documentation |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
|
|
|
Pickles a value, then writes the document to a string.
|
|
|
The zero pickler
Encodes nothing, 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 .
The schema must be attached later, e.g. in xpPair or other higher level combinators
|
|
|
Combine two picklers sequentially.
If the first fails during
unpickling, the whole unpickler fails
|
|
|
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.
|
|
|
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
|
|
|
Like xpPair but for triples
|
|
|
Like xpPair and xpTriple but for 4-tuples
|
|
|
Like xpPair and xpTriple but for 5-tuples
|
|
|
Like xpPair and xpTriple but for 6-tuples
|
|
|
Like xpPair and xpTriple but for 7-tuples
Thanks to Tony Morris for doing xp7Tuple, ..., xp24Tuple.
|
|
|
|
|
|
|
|
xp11Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU (a, b, c, d, e, f, g, h, i, j, k) | Source |
|
|
xp12Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU (a, b, c, d, e, f, g, h, i, j, k, l) | Source |
|
|
xp13Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m) | Source |
|
|
xp14Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n) | Source |
|
|
xp15Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) | Source |
|
|
xp16Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p) | Source |
|
|
xp17Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q) | Source |
|
|
xp18Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r) | Source |
|
|
xp19Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s) | Source |
|
|
xp20Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t) | Source |
|
|
xp21Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU u -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u) | Source |
|
|
xp22Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU u -> PU v -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v) | Source |
|
|
xp23Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU u -> PU v -> PU w -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w) | Source |
|
|
xp24Tuple :: PU a -> PU b -> PU c -> PU d -> PU e -> PU f -> PU g -> PU h -> PU i -> PU j -> PU k -> PU l -> PU m -> PU n -> PU o -> PU p -> PU q -> PU r -> PU s -> PU t -> PU u -> PU v -> PU w -> PU x -> PU (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x) | Source |
|
Hopefully no one needs a xp25Tuple
|
|
|
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
|
|
|
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.
|
|
|
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 a possibly empty string with a datatype description into an XML node.
Like xpText0 but with extra Parameter for datatype description as in xpTextDT.
|
|
|
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
|
|
|
Pickle an XmlTree by just adding it
Usefull for components of type XmlTree in other data structures
|
|
|
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.
|
|
|
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
|
|
|
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
|
|
|
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
|
|
|
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
|
|
|
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".
|
|
|
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
|
|
|
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 given as a QName. THE pickler for constructing
nested structures
Example:
xpElemQN (mkName "number") $ xpickle
will map an (42::Int) onto
<number>42</number>
|
|
|
convenient Pickler for xpElemQN
xpElem n = xpElemQN (mkName n)
|
|
|
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)
|
|
|
Pickler for storing/retreiving data into/from an attribute value
The attribute is inserted in the surrounding element constructed by the xpElem pickler
|
|
|
convenient Pickler for xpAttrQN
xpAttr n = xpAttrQN (mkName n)
|
|
|
A text attribute.
|
|
|
Add an optional attribute for an optional value (Maybe a).
|
|
|
|
|
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 | |
|
|
Produced by Haddock version 2.6.1 |