diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,10 @@ +## 1.9.0 + +* Remove deprecated functions (`ignoreTag`, `ignoreAllTreesContent`, `takeAllTreesContent`) +* Rename `parseText'` into `parseText` +* `takeContent` and `ignoreContent` now cover entities +* Align behaviour of `take`* and `ignore`* functions + ## 1.8.0.1 * Use doctest to validate code examples from documentation diff --git a/Text/XML/Stream/Parse.hs b/Text/XML/Stream/Parse.hs --- a/Text/XML/Stream/Parse.hs +++ b/Text/XML/Stream/Parse.hs @@ -17,7 +17,7 @@ -- As a simple example: -- -- >>> :set -XOverloadedStrings --- >>> import Data.Conduit (runConduit, (.|)) +-- >>> import Conduit (runConduit, (.|)) -- >>> import Data.Text (Text, unpack) -- >>> import Data.XML.Types (Event) -- >>> data Person = Person Int Text Text deriving Show @@ -68,7 +68,6 @@ ( -- * Parsing XML files parseBytes , parseBytesPos - , parseText' , parseText , parseTextPos , detectUtf @@ -93,18 +92,16 @@ , content , contentMaybe -- * Ignoring tags/trees - , ignoreTag , ignoreEmptyTag , ignoreTree + , ignoreContent , ignoreTreeContent , ignoreAnyTreeContent - , ignoreAllTreesContent -- * Streaming events , takeContent , takeTree , takeTreeContent , takeAnyTreeContent - , takeAllTreesContent -- * Tag name matching , NameMatcher(..) , matching @@ -314,7 +311,7 @@ -- provided by libxml-enumerator. However, this has the advantage of not -- relying on any C libraries. -- --- This relies on 'detectUtf' to determine character encoding, and 'parseText'' +-- This relies on 'detectUtf' to determine character encoding, and 'parseText' -- to do the actual parsing. parseBytes :: MonadThrow m => ParseSettings @@ -347,18 +344,11 @@ -- advantage of not relying on any C libraries. -- -- Since 1.2.4 -parseText' :: MonadThrow m - => ParseSettings - -> ConduitT T.Text Event m () -parseText' = mapOutput snd . parseTextPos +parseText :: MonadThrow m => ParseSettings -> ConduitT T.Text Event m () +parseText = mapOutput snd . parseTextPos -{-# DEPRECATED parseText "Please use 'parseText'' or 'parseTextPos'." #-} -parseText :: MonadThrow m - => ParseSettings - -> ConduitT T.Text EventPos m () -parseText = parseTextPos --- | Same as 'parseText'', but includes the position of each event. +-- | Same as 'parseText', but includes the position of each event. -- -- Since 1.2.4 parseTextPos :: MonadThrow m @@ -640,7 +630,7 @@ data ContentType = Ignore | IsContent Text | IsError String | NotContent -- | Grabs the next piece of content if available. This function skips over any --- comments and instructions and concatenates all content until the next start +-- comments, instructions or entities, and concatenates all content until the next start -- or end tag. contentMaybe :: MonadThrow m => ConduitT Event o m (Maybe Text) contentMaybe = do @@ -789,46 +779,85 @@ ignoreEmptyTag nameMatcher = tagIgnoreAttrs nameMatcher (return ()) -{-# DEPRECATED ignoreTag "Please use 'ignoreEmptyTag'." #-} -ignoreTag :: MonadThrow m - => NameMatcher a -- ^ Check if this is a correct tag name - -> ConduitT Event o m (Maybe ()) -ignoreTag = ignoreEmptyTag +ignored :: Monad m => ConduitT i o m () +ignored = fix $ \recurse -> do + event <- await + case event of + Just _ -> recurse + _ -> return () --- | Ignore a tag, its attributes and its children subtrees recursively. --- Both content and text events are ignored. --- This function returns @Just ()@ if the tag matched. +-- | Same as `takeTree`, without yielding `Event`s. -- +-- >>> :set -XOverloadedStrings +-- >>> import Conduit +-- +-- >>> runConduit $ parseLBS def "content" .| (ignoreTree "a" ignoreAttrs >> sinkList) +-- [EventBeginElement (Name {nameLocalName = "b", ...}) [],EventEndElement (Name {nameLocalName = "b", ...}),EventEndDocument] +-- +-- >>> runConduit $ parseLBS def "content" .| (ignoreTree "b" ignoreAttrs >> sinkList) +-- [EventBeginElement (Name {nameLocalName = "a", ...}) [],EventContent (ContentText "content"),EventEndElement (Name {nameLocalName = "a", ...}),EventEndDocument] +-- +-- >>> runConduit $ parseLBS def "content" .| (ignoreTree anyName ignoreAttrs >> sinkList) +-- [EventContent (ContentText "content"),EventBeginElement (Name {nameLocalName = "a", ...}) [],EventEndElement (Name {nameLocalName = "a", ...}),EventEndDocument] +-- +-- Since 1.9.0 +ignoreTree :: MonadThrow m => NameMatcher a -> AttrParser b -> ConduitT Event o m (Maybe ()) +ignoreTree nameMatcher attrParser = fuseUpstream (takeTree nameMatcher attrParser) ignored + +-- | Same as `takeContent`, without yielding `Event`s. +-- +-- >>> :set -XOverloadedStrings +-- >>> import Conduit +-- +-- >>> runConduit $ parseLBS def "content" .| (ignoreContent >> sinkList) +-- [EventBeginElement (Name {nameLocalName = "a", ...}) [],EventContent (ContentText "content"),EventEndElement (Name {nameLocalName = "a", ...}),EventEndDocument] +-- +-- >>> runConduit $ parseLBS def "content" .| (ignoreContent >> sinkList) +-- [EventBeginElement (Name {nameLocalName = "a", ...}) [],EventEndElement (Name {nameLocalName = "a", ...}),EventEndDocument] +-- +-- >>> runConduit $ parseLBS def "content" .| (ignoreContent >> sinkList) +-- [EventBeginElement (Name {nameLocalName = "a", ...}) [],EventEndElement (Name {nameLocalName = "a", ...}),EventEndDocument] +-- +-- Since 1.9.0 +ignoreContent :: MonadThrow m => ConduitT Event o m (Maybe ()) +ignoreContent = fuseUpstream takeContent ignored + + +-- | Same as `takeTreeContent`, without yielding `Event`s. +-- +-- >>> :set -XOverloadedStrings +-- >>> import Conduit +-- +-- >>> runConduit $ parseLBS def "content" .| (ignoreTreeContent "a" ignoreAttrs >> sinkList) +-- [EventBeginElement (Name {nameLocalName = "b", ...}) [],EventEndElement (Name {nameLocalName = "b", ...}),EventEndDocument] +-- +-- >>> runConduit $ parseLBS def "content" .| (ignoreTreeContent "b" ignoreAttrs >> sinkList) +-- [EventBeginElement (Name {nameLocalName = "a", ...}) [],EventContent (ContentText "content"),EventEndElement (Name {nameLocalName = "a", ...}),EventEndDocument] +-- +-- >>> runConduit $ parseLBS def "content" .| (ignoreTreeContent anyName ignoreAttrs >> sinkList) +-- [EventBeginElement (Name {nameLocalName = "a", ...}) [],EventEndElement (Name {nameLocalName = "a", ...}),EventEndDocument] +-- -- Since 1.5.0 -ignoreTreeContent :: MonadThrow m - => NameMatcher a -- ^ Check if this is a correct tag name - -> ConduitT Event o m (Maybe ()) -ignoreTreeContent namePred = tagIgnoreAttrs namePred (void $ many ignoreAnyTreeContent) +ignoreTreeContent :: MonadThrow m => NameMatcher a -> AttrParser b -> ConduitT Event o m (Maybe ()) +ignoreTreeContent namePred attrParser = fuseUpstream (takeTreeContent namePred attrParser) ignored -{-# DEPRECATED ignoreTree "Please use 'ignoreTreeContent'." #-} -ignoreTree :: MonadThrow m - => NameMatcher a -- ^ Check if this is a correct tag name - -> ConduitT Event o m (Maybe ()) -ignoreTree = ignoreTreeContent --- | Like 'ignoreTreeContent', but matches any name and also ignores content events. +-- | Same as `takeAnyTreeContent`, without yielding `Event`s. -- -- >>> :set -XOverloadedStrings --- >>> import Data.Conduit --- >>> import Data.Conduit.List (consume) +-- >>> import Conduit -- --- >>> runConduit $ parseLBS def "content" .| (ignoreAnyTreeContent >> consume) +-- >>> runConduit $ parseLBS def "content" .| (ignoreAnyTreeContent >> sinkList) -- [EventBeginElement (Name {nameLocalName = "b", ...}) [],EventEndElement (Name {nameLocalName = "b", ...}),EventEndDocument] -- --- >>> runConduit $ parseLBS def "text" .| (ignoreAnyTreeContent >> consume) +-- >>> runConduit $ parseLBS def "text" .| (ignoreAnyTreeContent >> sinkList) -- [EventBeginElement (Name {nameLocalName = "b", ...}) [],EventEndElement (Name {nameLocalName = "b", ...}),EventEndDocument] +-- +-- Since 1.5.0 ignoreAnyTreeContent :: MonadThrow m => ConduitT Event o m (Maybe ()) -ignoreAnyTreeContent = (void <$> contentMaybe) `orE` ignoreTreeContent anyName +ignoreAnyTreeContent = fuseUpstream takeAnyTreeContent ignored -{-# DEPRECATED ignoreAllTreesContent "Please use 'ignoreAnyTreeContent'." #-} -ignoreAllTreesContent :: MonadThrow m => ConduitT Event o m (Maybe ()) -ignoreAllTreesContent = ignoreAnyTreeContent -- | Get the value of the first parser which returns 'Just'. If no parsers -- succeed (i.e., return @Just@), this function returns 'Nothing'. @@ -1034,7 +1063,7 @@ many' :: MonadThrow m => ConduitT Event o m (Maybe a) -> ConduitT Event o m [a] -many' consumer = manyIgnore consumer ignoreAllTreesContent +many' consumer = manyIgnore consumer ignoreAnyTreeContent -- | Like 'many', but uses 'yield' so the result list can be streamed @@ -1060,20 +1089,32 @@ manyYield' :: MonadThrow m => ConduitT Event b m (Maybe b) -> ConduitT Event b m () -manyYield' consumer = manyIgnoreYield consumer ignoreAllTreesContent +manyYield' consumer = manyIgnoreYield consumer ignoreAnyTreeContent --- | Stream a content 'Event'. If next event isn't a content, nothing is consumed. +-- | Stream a single content 'Event'. -- -- Returns @Just ()@ if a content 'Event' was consumed, @Nothing@ otherwise. -- +-- >>> :set -XOverloadedStrings +-- >>> import Control.Monad (void) +-- >>> import Conduit +-- +-- >>> runConduit $ parseLBS def "content" .| void takeContent .| sinkList +-- [EventBeginDocument,EventContent (ContentText "content")] +-- +-- If next event isn't a content, nothing is consumed. +-- +-- >>> runConduit $ parseLBS def "content" .| void takeContent .| sinkList +-- [EventBeginDocument] +-- -- Since 1.5.0 takeContent :: MonadThrow m => ConduitT Event Event m (Maybe ()) takeContent = do event <- await case event of - Just e@(EventContent ContentText{}) -> yield e >> return (Just ()) - Just e@EventCDATA{} -> yield e >> return (Just ()) + Just e@EventContent{} -> yield e >> return (Just ()) + Just e@EventCDATA{} -> yield e >> return (Just ()) Just e -> if isWhitespace e then yield e >> takeContent else leftover e >> return Nothing _ -> return Nothing @@ -1081,23 +1122,22 @@ -- -- >>> :set -XOverloadedStrings -- >>> import Control.Monad (void) --- >>> import Data.Conduit --- >>> import Data.Conduit.List (consume) +-- >>> import Conduit -- --- >>> runConduit $ parseLBS def "content" .| void (takeTree "a" ignoreAttrs) .| consume +-- >>> runConduit $ parseLBS def "content" .| void (takeTree "a" ignoreAttrs) .| sinkList -- [EventBeginDocument,EventBeginElement (Name {nameLocalName = "a", ...}) [],EventContent (ContentText "content"),EventEndElement (Name {nameLocalName = "a", ...})] -- --- >>> runConduit $ parseLBS def "content" .| void (takeTree "b" ignoreAttrs) .| consume +-- >>> runConduit $ parseLBS def "content" .| void (takeTree "b" ignoreAttrs) .| sinkList -- [EventBeginDocument] -- -- If next 'Event' isn't an element, nothing is consumed. -- --- >>> runConduit $ parseLBS def "text" .| void (takeTree "a" ignoreAttrs) .| consume +-- >>> runConduit $ parseLBS def "text" .| void (takeTree "a" ignoreAttrs) .| sinkList -- [EventBeginDocument] -- -- If an opening-tag is consumed but no matching closing-tag is found, an 'XmlException' is thrown. -- --- >>> runConduit $ parseLBS def "" .| void (takeTree "a" ignoreAttrs) .| consume +-- >>> runConduit $ parseLBS def "" .| void (takeTree "a" ignoreAttrs) .| sinkList -- *** Exception: InvalidEndElement (Name {nameLocalName = "a", nameNamespace = Nothing, namePrefix = Nothing}) Nothing -- -- This function automatically ignores comments, instructions and whitespace. @@ -1128,37 +1168,42 @@ -- | Like 'takeTree', but can also stream a content 'Event'. -- +-- >>> :set -XOverloadedStrings +-- >>> import Control.Monad (void) +-- >>> import Conduit +-- +-- >>> runConduit $ parseLBS def "content" .| void (takeTreeContent "a" ignoreAttrs) .| sinkList +-- [EventBeginDocument,EventBeginElement (Name {nameLocalName = "a", ...}) [],EventContent (ContentText "content"),EventEndElement (Name {nameLocalName = "a", ...})] +-- +-- >>> runConduit $ parseLBS def "content" .| void (takeTreeContent "b" ignoreAttrs) .| sinkList +-- [EventBeginDocument] +-- +-- >>> runConduit $ parseLBS def "content" .| void (takeTreeContent "a" ignoreAttrs) .| sinkList +-- [EventBeginDocument,EventContent (ContentText "content")] +-- -- Since 1.5.0 -takeTreeContent :: MonadThrow m - => NameMatcher a - -> AttrParser b - -> ConduitT Event Event m (Maybe ()) +takeTreeContent :: MonadThrow m => NameMatcher a -> AttrParser b -> ConduitT Event Event m (Maybe ()) takeTreeContent nameMatcher attrParser = runMaybeT $ MaybeT (takeTree nameMatcher attrParser) <|> MaybeT takeContent -- | Like 'takeTreeContent', without checking for tag name or attributes. -- -- >>> :set -XOverloadedStrings -- >>> import Control.Monad (void) --- >>> import Data.Conduit ((.|), runConduit) --- >>> import Data.Conduit.List (consume) +-- >>> import Conduit -- --- >>> runConduit $ parseLBS def "text" .| void takeAnyTreeContent .| consume +-- >>> runConduit $ parseLBS def "text" .| void takeAnyTreeContent .| sinkList -- [EventBeginDocument,EventContent (ContentText "text")] -- --- >>> runConduit $ parseLBS def "" .| void takeAnyTreeContent .| consume +-- >>> runConduit $ parseLBS def "" .| void takeAnyTreeContent .| sinkList -- [EventBeginDocument] -- --- >>> runConduit $ parseLBS def "text" .| void takeAnyTreeContent .| consume +-- >>> runConduit $ parseLBS def "text" .| void takeAnyTreeContent .| sinkList -- [EventBeginDocument,EventBeginElement (Name {nameLocalName = "b", ...}) [],EventBeginElement (Name {nameLocalName = "c", ...}) [],EventEndElement (Name {nameLocalName = "c", ...}),EventEndElement (Name {nameLocalName = "b", ...})] -- -- Since 1.5.0 takeAnyTreeContent :: MonadThrow m => ConduitT Event Event m (Maybe ()) takeAnyTreeContent = takeTreeContent anyName ignoreAttrs - -{-# DEPRECATED takeAllTreesContent "Please use 'takeAnyTreeContent'." #-} -takeAllTreesContent :: MonadThrow m => ConduitT Event Event m (Maybe ()) -takeAllTreesContent = takeAnyTreeContent -- | Default implementation of 'DecodeEntities', which leaves the diff --git a/xml-conduit.cabal b/xml-conduit.cabal --- a/xml-conduit.cabal +++ b/xml-conduit.cabal @@ -1,5 +1,5 @@ name: xml-conduit -version: 1.8.0.1 +version: 1.9.0.0 license: MIT license-file: LICENSE author: Michael Snoyman , Aristid Breitkreuz @@ -13,6 +13,7 @@ homepage: http://github.com/snoyberg/xml extra-source-files: README.md ChangeLog.md +tested-with: GHC >=8.0 && <8.8 library build-depends: base >= 4 && < 5