Data.XML.Pickle

This module provides XML picklers that plug into the xml tree of the xml-types package. This module was "inspired" by hexpat-pickle.

The API differences between hexpat-pickle and this module include:

• When unpickling, picklers will consume matching elmements so that they will be ignored by sucessive picklers. To circumvent this behaviour, use xpPeek
• wrappers like xpWrap are uncurried
• There are no lazy unpicklers
• Unpicklers keep track of whether they (and any nested picklers) consumed all input, giving rise to the xpClean and xpRecursiveClean combinators

The data type PU t a represents both a pickler (converting Haskell data to XML) and an unpickler (XML to Haskell data), so your code only needs to be written once for both serialization and deserialization. The PU primitives, such as xpElem for XML elements, may be composed into complex arrangements using xpPair and other combinators.

The reason why you a list of nodes instead of just one when working with a single element is because the unpickler of xpElem needs to see the whole list of nodes so that it can 1. skip whitespace, and 2. search to match the specified tag name.

Most picklers will try to find the first match rather than failing when the first element doesn't match. This is why the target type often ist a list. To prevent this behaviour and commit the pickler to the first element available, use xpIsolate.

The top level of the document does not follow this rule, because it is a single node type. xpRoot is needed to adapt this to type [Node] for your pickler to use. You would typically define a pickler for a whole document with xpElem, then pickle it to a single Node with pickleTree (xpRoot myDocPickler) value.

NB: Unresolved entities are considered an error and will trigger an exception

When unpickling, the folowing invariant regarding the list of remaining elements should be observed: * The returned list should be a subset of or the initial list itself, that is, no elements should be added or changed * The relative order of elements should be preserved * Elements may, however, be removed from anywhere in the list

Here is a simple example to get you started:

 {-# LANGUAGE OverloadedStrings #-}
 import Data.Text
 import Data.XML.Types
 import Data.XML.Pickle

 -- Person name, age and description
 data Person = Person Text Int Text

 xpPerson :: PU [Node] Person
 xpPerson =
     -- How to wrap and unwrap a Person
     xpWrap (\((name, age), descr) -> Person name age descr)
            (\(Person name age descr) -> ((name, age), descr)) $
     xpElem "person"
         (xpPair
             (xpAttr "name" xpId)
             (xpAttr "age" xpPrim))
         (xpContent xpId)

 people = [
     Person "Dave" 27 "A fat thin man with long short hair",
     Person "Jane" 21 "Lives in a white house with green windows"]

 main = do
     print $ pickle (xpRoot $ xpElemNodes "people" $ xpAll xpPerson) people

Program outputs would be an xml-value equivalent to:

 <people><person name="Dave" age="27">A fat thin man with long short hair</person>
 <person name="Jane" age="21">Lives in a white house with green windows</person></people>

Funktions marked with compat are included for compatibility with hexpat-pickle

Types

data PU t a

Constructors

PU

Fields

unpickleTree :: t -> Either UnpickleError (a, (Maybe t, Bool))

Either an error or the return value, any remaining input and a Bool value indicating whether all nested picklers where clean

pickleTree :: a -> t

Instances

Category PU

type Attribute = (Name, [Content])

Pickler Invocation

pickle :: PU t a -> a -> t

pickle a Tree

unpickle :: PU t a -> t -> Either UnpickleError a

unpickle a tree, throws away information concerning cleannes

Primitive picklers

xpUnit :: PU [a] ()

Doesn't create or consume anything, always succeeds

xpZero :: PU [t] a

The zero pickler

Encodes nothing, always fails during unpickling. (Same as xpThrow "got xpZero").

xpThrow

Arguments

:: String

Error message

-> PU [t] a

No output when pickling, always generates an error with the specified message on unpickling.

Value-preserving picklers

xpId :: PU a a

Returns everything (remaining), untouched.

xpTrees :: PU a a

xpId (compat)

xpHead :: PU [a] a

return one element, untouched

xpTree :: PU [a] a

xpHead (compat)

xpText0 :: PU Text Text

specialised version of xpId (compat)

xpText :: PU Text Text

Like xpText0, but fails on non-empty input.

xpRoot :: PU [a] b -> PU a b

Adapts a list of nodes to a single node. Generally used at the top level of an XML document.

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

Convert XML text content <-> any type that implements Read and Show. Fails on unpickle if read fails.

XML specific picklers

Attributes

xpAttr :: Name -> PU Text a -> PU [Attribute] a

pickle to/from attribute

xpAttrImplied :: Name -> PU Text a -> PU [Attribute] (Maybe a)

Pickle attribute if Just is given, on unpickling return Just val when the attribute is found, Nothing otherwise

xpAttrFixed :: Name -> Text -> PU [Attribute] ()

Pickle an attribute with the specified name and value, fail if the same attribute is not present on unpickle.

Elements

xpElem

Arguments

:: Name

name of the Element

-> PU [Attribute] a

pickler for attributes

-> PU [Node] n

pickler for child nodes

-> PU [Node] (a, n)

When unpickling, tries to find the first element with the supplied name. Once such an element is found, it will commit to it and fail if any of the picklers don't match.

xpElemWithName

Arguments

:: PU [Attribute] a

pickler for attributes

-> PU [Node] n

pickler for child nodes

-> PU [Node] (Name, a, n)

pickle Element without restriction on the name. the name as taken / returned as the first element of the triple

xpElemByNamespace

Arguments

:: Text

Namespace

-> PU Text name

Pickler for the local name

-> PU [Attribute] a

pickler for attributes

-> PU [Node] n

pickler for child nodes

-> PU [Node] (name, a, n)

find element by name space, prefixes are ignored

xpElemVerbatim :: PU [Node] Element

use Element untouched

xpElemAttrs :: Name -> PU [Attribute] b -> PU [Node] b

A helper variant of xpElem for elements that contain attributes but no child tags.

xpElemNodes :: Name -> PU [Node] b -> PU [Node] b

A helper variant of xpElem for elements that contain child nodes but no attributes.

xpElemBlank :: Name -> PU [Node] ()

Helper for Elements that don't contain anything

xpElemExists :: Name -> PU [Node] Bool

When pickling, creates an empty element iff parameter is True

When unpickling, checks whether element exists

xpElems

Arguments

:: Name

Name of the elements

-> PU [Attribute] a

pickler for attributes

-> PU [Node] n

pickler for child nodes

-> PU [Node] [(a, n)]

Handle all elements with a given name. The unpickler will fail when any of the elements fails to unpickle.

Character Content

xpContent :: PU Text a -> PU [Node] a

Get the Content from a node

Pickler combinators

choice

xpOption :: PU [t] a -> PU [t] (Maybe a)

Convert XML text <-> a Maybe type. During unpickling, Nothing is returned if there's a failure during the unpickling of the first argument. A typical example is:

 xpElemAttrs "score" $ xpOption $ xpAttr "value" xpickle

in which Just 5 would be encoded as <score value="5"/> and Nothing would be encoded as <score/>.

xpDefault :: Eq a => a -> PU [t] a -> PU [t] a

Optional conversion with default value

Unlike xpWithDefault the default value is not encoded in the XML document, during unpickling the default value is inserted if the pickler fails

xpWithDefault :: a -> PU t a -> PU t a

Attempt to use a pickler. On failure, return a default value.

Unlike xpDefault, the default value is encoded in the XML document.

xpMap

Arguments

:: Ord k

=> Name

Element name (elt)

-> Name

Attribute name (attr)

-> PU Text k

Pickler for keys (key)

-> PU [Node] a

Pickler for values (value)

-> PU [Node] (Map k a)

Standard pickler for maps

This pickler converts a map into a list of pairs of the form

 <elt attr="key">value</elt>

xpAlt

Arguments

:: (a -> Int)

selector function

-> [PU t a]

list of picklers

-> PU t a

Execute one of a list of picklers. The selector function is used during pickling, and the integer returned is taken as a 0-based index to select a pickler from pickler options. Unpickling is done by trying each list element in order until one succeeds (the selector is not used).

This is typically used to handle each constructor of a data type. However, it can be used wherever multiple serialization strategies apply to a single type.

xpEither :: PU n t1 -> PU n t2 -> PU n (Either t1 t2)

Try the left pickler first and if that failes the right one. wrapping the result in Left or Right, respectively

Not to be confued with xpWrapEither

xpTryCatch :: PU t a -> PU t a -> PU t a

Pickler that during pickling always uses the first pickler, and during unpickling tries the first, and on failure then tries the second.

sequencing

NB The sequencing operations do not enforce any order on the matched elements unless stated otherwise, but you can commit individial picklers to the next available element with xpIsolate. Applying xpIsolate on all nested Picklers will in effect enforce order.

Howver, once a pickler consumes an element it will not be available to following picklers. You can circumvent this behaviour with xpPeek.

If you want ensure that all elements are consumed after the last pickler is run you may want to use xpClean

Lists

The List pickler combinators will pickle lists in the given order without any special treatment and unpickle as stated.

xpFindMatches :: PU [b] a -> PU [b] [a]

When unpickling, tries to apply the pickler to all elements returning and consuming only matched elements

xpAll :: PU [a] b -> PU [a] [b]

Tries to apply the pickler to all the remaining elements; fails if any of them don't match

xpSubsetAll

Arguments

:: (a -> Bool)

predicate to select the subset

-> PU [a] b

pickler to apply on the subset

-> PU [a] [b]

For unpickling, apply the given pickler to a subset of the elements determined by a given predicate

Pickles like xpAll

xpList0 :: PU [a] b -> PU [a] [b]

xpAll (compat)

xpSeqWhile :: PU [a] b -> PU [a] [b]

When unpickling, sucessively applies pickler to single elements until it fails; returns all matched elements.

xpList :: PU [a] b -> PU [a] [b]

xpSeqWhile (compat)

Tuples

Tuple combinators apply their picklers from left to right

xp2Tuple :: PU [a] b1 -> PU [a] b2 -> PU [a] (b1, b2)

Combines 2 picklers

xpPair :: PU [a] b1 -> PU [a] b2 -> PU [a] (b1, b2)

xp2Tuple (compat)

(<#>) :: PU [a] b1 -> PU [a] b2 -> PU [a] (b1, b2)

xp2Tuple

xp3Tuple :: PU [a] a1 -> PU [a] a2 -> PU [a] a3 -> PU [a] (a1, a2, a3)

Combines 3 picklers

xpTriple :: PU [a] a1 -> PU [a] a2 -> PU [a] a3 -> PU [a] (a1, a2, a3)

xp3Tuple (compat)

xp4Tuple :: PU [a] a1 -> PU [a] a2 -> PU [a] a3 -> PU [a] a4 -> PU [a] (a1, a2, a3, a4)

Combines 4 picklers

xp5Tuple :: PU [a] a1 -> PU [a] a2 -> PU [a] a3 -> PU [a] a4 -> PU [a] a5 -> PU [a] (a1, a2, a3, a4, a5)

Combines 5 picklers

xp6Tuple :: PU [a] a1 -> PU [a] a2 -> PU [a] a3 -> PU [a] a4 -> PU [a] a5 -> PU [a] a6 -> PU [a] (a1, a2, a3, a4, a5, a6)

You guessed it ... Combines 6 picklers

Wrappers

value wrappers

xpWrap :: (a -> b) -> (b -> a) -> PU t a -> PU t b

apply a bijection before pickling / after unpickling

xpWrapEither :: (a -> Either String b) -> (b -> a) -> PU t a -> PU t b

Like xpWrap, except it strips Right (and treats Left as a failure) during unpickling. xpWrapEither :: (a -> Either String b, b -> a) -> PU t a -> PU t b

not to be confuesd with xpEither

xpWrapMaybe :: (a -> Maybe b) -> (b -> a) -> PU t a -> PU t b

Like xpWrap, but strips Just (and treats Nothing as a failure) during unpickling.

xpWrapMaybe_ :: String -> (a -> Maybe b) -> (b -> a) -> PU t a -> PU t b

Like xpWrap, but strips Just (and treats Nothing as a failure) during unpickling, with specified error message for Nothing value.

xpAssert :: Text -> (a -> Bool) -> PU t a -> PU t a

Test predicate when unpickling. Fails with given error message when the predicate return false.

N.B.: The predicate will only be tested while unpickling. When pickling, this is a noop.

xpUnliftElems :: PU [Node] a -> PU [Element] a

Unlift a pickler on Nodes to a Pickler on Elements. Nodes generated during pickling that are not Elements will be silently discarded

Book keeping

Change the semantics of picklers

xpIsolate :: PU [t] a -> PU [t] a

Noop when pickling

When unpickling, only give access to the first element

xpPeek :: PU t a -> PU t a

When unpickling, don't consume the matched element(s), noop when pickling

Cleannes

Picklers keep track of elements left over after unpickling, so the may be

clean

an unpickling is considered clean when it doesn't leave any remainng elements

recursively clean

an unpickling is considered recursively clean if it and any nested picklers are clean

xpClean :: PU t a -> PU t a

When unpickling check that all elements have been consumed after this pickler, fails otherwise

When pickling, this is a noop

xpRecursiveClean :: PU t a -> PU t a

When unpickling check that all elements have been consumed and that the same is true for all nested picklers, fails otherwise

When pickling, this is a noop

Error handling

data UnpickleError

Constructors

ErrorMessage Text

TraceStep (Text, Text) UnpickleError

Variants [UnpickleError]

Instances

Show UnpickleError

Typeable UnpickleError

Exception UnpickleError

(<++>) :: (Text, Text) -> UnpickleError -> UnpickleError

(<?+>) :: (Text, Text) -> PU t a -> PU t a

(<?>) :: (Text, Text) -> PU t a -> PU t a

data UnresolvedEntityException

Constructors

UnresolvedEntityException

Instances

Show UnresolvedEntityException

Typeable UnresolvedEntityException

Exception UnresolvedEntityException

helper functions

flattenContent :: [Node] -> [Node]