xml-extractors 0.4.0.0 → 0.4.0.1
raw patch · 3 files changed
+79/−37 lines, 3 filesdep ~basedep ~mtldep ~transformersPVP ok
version bump matches the API change (PVP)
Dependency ranges changed: base, mtl, transformers
API changes (from Hackage documentation)
Files
- README.md +63/−10
- src/Text/XML/Light/Extractors.hs +4/−6
- xml-extractors.cabal +12/−21
README.md view
@@ -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+<?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 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+```
src/Text/XML/Light/Extractors.hs view
@@ -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 --------------------------------------------------------------------------------
xml-extractors.cabal view
@@ -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+