hxt-7.5: A collection of tools for processing XML with Haskell.ContentsIndex
Text.XML.HXT.Arrow.Pickle
Portabilityportable
Stabilityexperimental
MaintainerUwe Schmidt (uwe@fh-wedel.de)
Description

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)

Synopsis
xpickleDocument :: PU a -> Attributes -> String -> IOStateArrow s a XmlTree
xunpickleDocument :: PU a -> Attributes -> String -> IOStateArrow s b a
xpickleWriteDTD :: PU b -> Attributes -> String -> IOStateArrow s b XmlTree
xpickleDTD :: PU b -> IOStateArrow s b XmlTree
checkPickler :: Eq a => PU a -> IOStateArrow s a a
xpickleVal :: ArrowXml a => PU b -> a b XmlTree
xunpickleVal :: ArrowXml a => PU b -> a XmlTree b
thePicklerDTD :: PU b -> XmlTrees
a_addDTD :: String
pickleDoc :: PU a -> a -> XmlTree
unpickleDoc :: PU a -> XmlTree -> Maybe a
data PU a = PU {
appPickle :: (a, St) -> St
appUnPickle :: St -> (Maybe a, St)
theSchema :: Schema
}
class XmlPickler a where
xpickle :: PU a
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)
xpAddFixedAttr :: String -> String -> PU a -> PU a
xpAlt :: (a -> Int) -> [PU a] -> PU a
xpAttr :: String -> PU a -> PU a
xpAttrFixed :: String -> String -> PU ()
xpAttrImplied :: String -> PU a -> PU (Maybe a)
xpChoice :: PU b -> PU a -> (a -> PU b) -> PU b
xpCondSeq :: PU b -> (b -> a) -> PU a -> (a -> PU b) -> PU b
xpElem :: String -> PU a -> PU a
xpickle :: XmlPickler a => PU a
xpLift :: a -> PU a
xpLiftMaybe :: Maybe a -> PU a
xpList :: PU a -> PU [a]
xpList1 :: PU a -> PU [a]
xpOption :: PU a -> PU (Maybe a)
xpPair :: PU a -> PU b -> PU (a, b)
xpPrim :: (Read a, Show a) => PU a
xpSeq :: (b -> a) -> PU a -> (a -> PU b) -> PU b
xpText :: PU String
xpText0 :: PU String
xpTextDT :: Schema -> PU String
xpText0DT :: Schema -> PU String
xpTree :: PU XmlTree
xpTriple :: PU a -> PU b -> PU c -> PU (a, b, c)
xpUnit :: PU ()
xpWrap :: (a -> b, b -> a) -> PU a -> PU b
xpWrapMaybe :: (a -> Maybe b, b -> a) -> PU a -> PU b
xpZero :: PU a
data Schema
type Schemas = [Schema]
data DataTypeDescr
Documentation
xpickleDocument :: PU a -> Attributes -> String -> IOStateArrow s a XmlTree

store an arbitray value in a persistent XML document

The pickler converts a value into an XML tree, this is written out with Text.XML.HXT.Arrow.writeDocument. The option list is passed to Text.XML.HXT.Arrow.writeDocument

An options evaluated by this arrow is a_addDTD. If a_addDTD is set (v_1), the pickler DTD is added as an inline DTD into the document.

xunpickleDocument :: PU a -> Attributes -> String -> IOStateArrow s b a

read an arbitray value from an XML document

The document is read with Text.XML.HXT.Arrow.readDocument. Options are passed to Text.XML.HXT.Arrow.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.

xpickleWriteDTD :: PU b -> Attributes -> String -> IOStateArrow s b XmlTree
Write out the DTD generated out of a pickler. Calls xpicklerDTD
xpickleDTD :: PU b -> IOStateArrow s b XmlTree

The arrow for generating the DTD out of a pickler

A DTD is generated from a pickler and check for consistency. Errors concerning the DTD are issued.

checkPickler :: Eq a => PU a -> IOStateArrow s a a

An arrow for checking picklers

A value is transformed into an XML document by a given pickler, the associated DTD is extracted from the pickler and checked, the document including the DTD is tranlated into a string, this string is read and validated against the included DTD, and unpickled. The last step is the equality with the input.

If the check succeeds, the arrow works like this, else it fails.

xpickleVal :: ArrowXml a => PU b -> a b XmlTree
The arrow version of the pickler function
xunpickleVal :: ArrowXml a => PU b -> a XmlTree b
The arrow version of the unpickler function
thePicklerDTD :: PU b -> XmlTrees
Compute the associated DTD of a pickler
a_addDTD :: String
Option for generating and adding DTD when document is pickled
pickleDoc :: PU a -> a -> XmlTree

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

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

data PU a
Constructors
PU
appPickle :: (a, St) -> St
appUnPickle :: St -> (Maybe a, St)
theSchema :: Schema
class XmlPickler a where
The class for overloading xpickle, the default pickler
Methods
xpickle :: PU a
show/hide Instances
xp4Tuple :: PU a -> PU b -> PU c -> PU d -> PU (a, b, c, d)
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)
Like xpPair and xpTriple but for 5-tuples
xpAddFixedAttr :: String -> String -> PU a -> PU a

Add an attribute with a fixed value.

Useful e.g. to declare namespaces. Is implemented by xpAttrFixed

xpAlt :: (a -> Int) -> [PU a] -> PU a

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

xpAttr :: String -> PU a -> PU a

Pickler for storing/retreiving data into/from an attribute value

The attribute is inserted in the surrounding element constructed by the xpElem pickler

xpAttrFixed :: String -> String -> PU ()
xpAttrImplied :: String -> PU a -> PU (Maybe a)
Add an optional attribute for an optional value (Maybe a).
xpChoice :: PU b -> PU a -> (a -> PU b) -> PU b

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.

xpCondSeq :: PU b -> (b -> a) -> PU a -> (a -> PU b) -> PU b

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

xpElem :: String -> PU a -> PU a

Pickler for wrapping/unwrapping data into an XML element

Extra parameter is the element name. THE pickler for constructing nested structures

xpickle :: XmlPickler a => PU a
xpLift :: a -> PU a

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

Lift a Maybe value to a pickler.

Nothing is mapped to the zero pickler, Just x is pickled with xpLift x.

xpList :: PU a -> PU [a]

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]

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".

xpOption :: PU a -> PU (Maybe a)

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

xpPair :: PU a -> PU b -> PU (a, b)

pickle a pair of values sequentially

Used for pairs or together with wrap for pickling algebraic data types with two components

xpPrim :: (Read a, Show a) => PU a

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

xpSeq :: (b -> a) -> PU a -> (a -> PU b) -> PU b

Combine two picklers sequentially.

If the first fails during unpickling, the whole unpickler fails

xpText :: PU String

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

xpText0 :: PU String

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.

xpTextDT :: Schema -> PU String

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.

xpText0DT :: Schema -> PU String

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.

xpTree :: PU XmlTree

Pickle an XmlTree by just adding it

Usefull for components of type XmlTree in other data structures

xpTriple :: PU a -> PU b -> PU c -> PU (a, b, c)
Like xpPair but for triples
xpUnit :: PU ()
xpWrap :: (a -> b, b -> a) -> PU a -> PU b

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

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

xpZero :: PU a

The zero pickler

Encodes nothing, fails always during unpickling

data Schema
The datatype for modelling the structure of an
show/hide Instances
type Schemas = [Schema]
data DataTypeDescr
show/hide Instances
Produced by Haddock version 2.1.0