Text.XML.Light.Extractors

Functions to extract data from parsed XML.

Example

Suppose you have an xml file of books like this:

<?xml version="1.0"?>
<library>
  <book id="1" isbn="23234-1">
    <author>John Doe</author>
    <title>Some book</title>
  </book>
  <book id="2">
    <author>You</author>
    <title>The Great Event</title>
  </book>
  ...
</library>

And a data type for a book:

data Book = Book { bookId        :: Int
                 , isbn          :: Maybe String
                 , author, title :: String
                 }

You can parse the xml file into a generic tree structure using parseXMLDoc from the xml package.

Using this library one can define extractors to extract Books from the generic tree.

   book = element "book" $ do
            i <- attribAs "id" integer
            s <- optional (attrib "isbn")
            children $ do
              a <- element "author" $ contents $ text
              t <- element "title" $ contents $ text
              return Book { bookId = i, author = a, title = t, isbn = s }

   library = element "library" $ children $ only $ many book

   extractLibrary :: Element -> Either ExtractionErr [Book]
   extractLibrary = extractDocContents library

Notes

• The only combinator can be used to exhaustively extract contents.

• The Control.Applicative module contains some useful combinators like optional, many and <|>.
• The Text.XML.Light.Extractors.ShowErr contains some predefined functions to convert error values to strings.

Errors

type Path = [String]

Location for some content.

For now it is a reversed list of content indices (starting at 1) and element names. This may change to something less "stringly typed".

data Err

Extraction errors.

Constructors

ErrExpectContent

Some expected content is missing

Fields

• expectedContent :: String
• foundContent :: Content

ErrExpectAttrib

An expected attribute is missing

Fields

• expectedAttrib :: String

  name of expected attribute

• atElement :: Element

  element with missing attribute

ErrAttribValue

An attribute value was bad

Fields

• expectedValue :: String

  description of expected value

• foundValue :: String

  the value found

• atElement :: Element

  element with missing attribute

ErrEnd

Expected end of contents

Fields

• foundContent :: Content

ErrNull

Unexpected end of contents

Fields

• expectedContent :: String

ErrMsg String

Instances

Show Err

Methods

showsPrec :: Int -> Err -> ShowS

show :: Err -> String

showList :: [Err] -> ShowS

data ExtractionErr

Error with a context.

Constructors

ExtractionErr

Fields

• err :: Err
• context :: Path

Instances

Show ExtractionErr

Methods

showsPrec :: Int -> ExtractionErr -> ShowS

show :: ExtractionErr -> String

showList :: [ExtractionErr] -> ShowS

Error ExtractionErr

Methods

noMsg :: ExtractionErr

strMsg :: String -> ExtractionErr

Element extraction

data ElementExtractor a

Instances

Monad ElementExtractor

Methods

(>>=) :: ElementExtractor a -> (a -> ElementExtractor b) -> ElementExtractor b

(>>) :: ElementExtractor a -> ElementExtractor b -> ElementExtractor b

return :: a -> ElementExtractor a

fail :: String -> ElementExtractor a

Functor ElementExtractor

Methods

fmap :: (a -> b) -> ElementExtractor a -> ElementExtractor b

(<$) :: a -> ElementExtractor b -> ElementExtractor a

Applicative ElementExtractor

Methods

pure :: a -> ElementExtractor a

(<*>) :: ElementExtractor (a -> b) -> ElementExtractor a -> ElementExtractor b

(*>) :: ElementExtractor a -> ElementExtractor b -> ElementExtractor b

(<*) :: ElementExtractor a -> ElementExtractor b -> ElementExtractor a

Alternative ElementExtractor

Methods

empty :: ElementExtractor a

(<|>) :: ElementExtractor a -> ElementExtractor a -> ElementExtractor a

some :: ElementExtractor a -> ElementExtractor [a]

many :: ElementExtractor a -> ElementExtractor [a]

extractElement :: ElementExtractor a -> Element -> Either ExtractionErr a

extractElement p element extracts element with p.

attrib :: String -> ElementExtractor String

attrib name extracts the value of attribute name.

attribAs :: String -> (String -> Either String a) -> ElementExtractor a

attribAs name f extracts the value of attribute name and runs it through a conversion/validation function.

The conversion function takes a string with the value and returns either a description of the expected format of the value or the converted value.

children :: ContentsExtractor a -> ElementExtractor a

children p extract only child elements with p.

contents :: ContentsExtractor a -> ElementExtractor a

contents p extract contents with p.

Contents extraction

data ContentsExtractor a

Instances

Monad ContentsExtractor

Methods

(>>=) :: ContentsExtractor a -> (a -> ContentsExtractor b) -> ContentsExtractor b

(>>) :: ContentsExtractor a -> ContentsExtractor b -> ContentsExtractor b

return :: a -> ContentsExtractor a

fail :: String -> ContentsExtractor a

Functor ContentsExtractor

Methods

fmap :: (a -> b) -> ContentsExtractor a -> ContentsExtractor b

(<$) :: a -> ContentsExtractor b -> ContentsExtractor a

Applicative ContentsExtractor

Methods

pure :: a -> ContentsExtractor a

(<*>) :: ContentsExtractor (a -> b) -> ContentsExtractor a -> ContentsExtractor b

(*>) :: ContentsExtractor a -> ContentsExtractor b -> ContentsExtractor b

(<*) :: ContentsExtractor a -> ContentsExtractor b -> ContentsExtractor a

Alternative ContentsExtractor

Methods

empty :: ContentsExtractor a

(<|>) :: ContentsExtractor a -> ContentsExtractor a -> ContentsExtractor a

some :: ContentsExtractor a -> ContentsExtractor [a]

many :: ContentsExtractor a -> ContentsExtractor [a]

extractContents :: ContentsExtractor a -> [Content] -> Either ExtractionErr a

extractContents p contents extracts the contents with p.

extractDocContents :: ContentsExtractor a -> Element -> Either ExtractionErr a

Using parseXMLDoc produces a single Element. Such an element can be extracted using this function.

element :: String -> ElementExtractor a -> ContentsExtractor a

element name p extracts a name element with p.

text :: ContentsExtractor String

Extracts text.

textAs :: (String -> Either Err a) -> ContentsExtractor a

Extracts text applied to a conversion function.

choice :: [ContentsExtractor a] -> ContentsExtractor a

Extracts first matching.

anyContent :: ContentsExtractor Content

Extracts one Content item.

eoc :: ContentsExtractor ()

Succeeds only when there is no more content.

only :: ContentsExtractor a -> ContentsExtractor a

only p fails if there is more contents than extracted by p.

only p = p <* eoc

Utils

showExtractionErr :: ExtractionErr -> String

Converts an extraction error to a multi line string message.

Paths are shown according to showPath.

eitherMessageOrValue :: Either ExtractionErr a -> Either String a

Convenience function to convert extraction errors to string messages using showExtractionErr.

eitherMessageOrValue = either (Left . showExtractionErr) Right

integer :: (Integral a, Read a) => String -> Either String a

Reads an integer value or return Left "integer" if the read fails.

float :: (Floating a, Read a) => String -> Either String a

Reads a floating point value or return Left "float" if the read fails.