diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,15 +1,68 @@ xml-extractors ============== -Simple wrapper over [xml](http://hackage.haskell.org/package/xml) to -extract data from parsed xml. +This is an extension to the +[xml](http://hackage.haskell.org/package/xml) package, providing +functions to extract data from parsed xml. -When parsing xml strings with `XML.Light` you get a list of -[Content](http://hackage.haskell.org/package/xml-1.3.13/docs/Text-XML-Light-Types.html#t:Content). Then -you can use functions from -[Text.XML.Light.Proc](http://hackage.haskell.org/package/xml-1.3.13/docs/Text-XML-Light-Proc.html) -to extract data from that. It is however kind of tricky to deal with -the potential errors -- we have a parsing problem again. -Instead of `Text.XML.Light.Proc` one can use this library. It simplifies -the process of extracting data from `Content` while dealing with errors. +## Motivation + +The `xml` package provides functions to parse and get information from +xml data. It will parse an xml string into a generic tree +representation. Extracting information from such a tree to some custom +data structure while keeping track of location to handle errors is +tricky. This library helps with that. + +If there is an error during extraction (expected information is absent +or wrong), it will return an error value with position +information. The idea is to provide decent error messages. + + +## Example usage + +Suppose you have an xml file of books like this: + +```xml + + + + John Doe + Some book + + + You + The Great Event + + ... + +``` + +and a Haskell data type to represent a book: + +```haskell +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. Then to transform this generic +xml tree into `Book` objects you define extractors for books, like +so: + +```haskell +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 +``` diff --git a/src/Text/XML/Light/Extractors.hs b/src/Text/XML/Light/Extractors.hs --- a/src/Text/XML/Light/Extractors.hs +++ b/src/Text/XML/Light/Extractors.hs @@ -29,20 +29,20 @@ -- You can parse the xml file into a generic tree structure using -- 'Text.XML.Light.Input.parseXMLDoc' from the `xml` package. -- --- Using this library one can define extractors to extract data from +-- Using this library one can define extractors to extract Books from -- the generic tree. -- -- @ --- library = 'element' "library" $ 'children' $ 'only' $ 'many' book --- -- book = 'element' "book" $ do -- i <- 'attribAs' "id" 'Text.XML.Light.Extractors.Extra.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 } +-- return Book { bookId = i, author = a, title = t, isbn = s } -- +-- library = 'element' "library" $ 'children' $ 'only' $ 'many' book +-- -- extractLibrary :: 'XML.Element' -> 'Either' 'ExtractionErr' [Book] -- extractLibrary = 'extractDocContents' library -- @ @@ -95,14 +95,12 @@ import Control.Applicative import Text.XML.Light.Types as XML -import qualified Text.XML.Light.Proc as XML import Text.XML.Light.Extractors.Extra import Text.XML.Light.Extractors.ShowErr (showExtractionErr) import Text.XML.Light.Extractors.Internal (ExtractionErr, Err, Path) import qualified Text.XML.Light.Extractors.Internal as Internal import Text.XML.Light.Extractors.Internal.Result hiding (throwError, throwFatal) -import qualified Text.XML.Light.Extractors.Internal.Result as R -------------------------------------------------------------------------------- diff --git a/xml-extractors.cabal b/xml-extractors.cabal --- a/xml-extractors.cabal +++ b/xml-extractors.cabal @@ -1,21 +1,11 @@ name: xml-extractors -version: 0.4.0.0 -synopsis: Wrapper over xml to extract data from parsed xml +version: 0.4.0.1 +synopsis: Extension to the xml package to extract data from parsed xml description: - This is a library to simplify extraction of data from parsed xml. - . - See the 'Text.XML.Light.Extractors' module for an example. - . - /Motivation/ - . - The `xml` package provides functions to parse and get information from - xml data. It will parse an xml string into a generic tree - representation. Extracting information from such a tree while - keeping track of location to handle errors is tricky. This library - helps with that. - . - If there is an error during extraction (expected information is - absent or wrong), it will return an error value with position information. + This library provides functions to simplify extraction of data from + generic xml tree structures (as produced by parsing xml with the `xml` package), + while handling location information to provide decent error messages in case + of errors. . /Some limitations/ . @@ -30,7 +20,7 @@ maintainer: holmisen@gmail.com -- copyright: category: XML -tested-with: GHC == 7.8.3, GHC == 7.8.4 +tested-with: GHC == 7.8.3, GHC == 7.8.4, GHC == 7.10.2 build-type: Simple extra-source-files: README.md, changelog.md cabal-version: >=1.10 @@ -43,11 +33,12 @@ Text.XML.Light.Extractors.ShowErr -- other-modules: other-extensions: NoMonomorphismRestriction - build-depends: base >=4.6 && <4.8, + build-depends: base >=4.6 && <4.9, xml >=1.3 && <1.4, - mtl >=2.1 && <2.2, - transformers >=0.3 && <0.4, + mtl >=2.1 && <2.3, + transformers >=0.3 && <0.5, safe >=0.3 && <0.4 hs-source-dirs: src default-language: Haskell2010 --- ghc-options: -Wall + ghc-options: -fno-warn-warnings-deprecations +