Documentation

Choice combinator for unpickling

first 2 arguments are applied sequentially, but if the 1. one fails the 3. arg is applied

Lift a Maybe value into the Unpickler monad.

The 1. arg is the attached error message

Lift an Either value into the Unpickler monad

Format the context of an error message.

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 does make sense. For reconverting a value from an XML tree, is becomes neccessary, to introduce "enough" markup for unpickling the value

Like unpickleDoc but with a (sometimes) useful error message, when unpickling failed.

The main entry for unpickling, called by unpickleDoc

Pickles a value, then writes the document to a string.

The zero pickler

Encodes nothing, fails always during unpickling

unit pickler

Check EOF pickler.

When pickling, this behaves like the unit pickler. The unpickler fails, when there is some unprocessed XML contents left.

Like xpCheckEmptyContents, but checks the attribute list

Composition of xpCheckEmptyContents and xpCheckAttributes

Lift a Maybe value to a pickler.

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

Combine two picklers sequentially.

If the first fails during unpickling, the whole unpickler fails

First apply a fixed pickler/unpickler, then a 2. one

If the first fails during unpickling, the whole pickler fails. This can be used to check some properties of the input, e.g. whether a given fixed attribute or a namespace declaration exists (xpAddFixedAttr, xpAddNSDecl) or to filter the input, e.g. to ignore some elements or attributes (xpFilterCont, xpFilterAttr).

When pickling, this can be used to insert some fixed XML pieces, e.g. namespace declarations, class attributes or other stuff.

combine two picklers with a choice

Run two picklers in sequence like with xpSeq. If 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

Deprecated: Use xpWrapEither, this gives better error messages

like xpWrap, but if the inverse mapping is undefined, the unpickler fails

Map a value into another domain. If the inverse mapping is undefined, the unpickler fails with an error message in the Left component

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.

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 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 Int

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)

convenient Pickler for xpElemQN for pickling elements with respect to namespaces

xpElemNS ns px lp = xpElemQN (mkQName px lp ns)

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)

convenient Pickler for xpAttrQN

xpAttr ns px lp = xpAttrQN (mkQName px lp ns)

A text attribute.

Add an optional attribute for an optional value (Maybe a).

Add/Check an attribute with a fixed value.

Add a namespace declaration.

When generating XML the namespace decl is added, when reading a document, the unpickler checks whether there is a namespace declaration for the given namespace URI (2. arg)

When unpickling, filter the contents of the element currently processed, before applying the pickler argument

Maybe useful to ignore some stuff in the input, or to do some cleanup before unpickling.

Same as xpFilterCont but for the attribute list of the element currently processed.

Maybe useful to ignore some stuff in the input, e.g. class attributes, or to do some cleanup before unpickling.

The class for overloading xpickle, the default pickler