feed
Interfacing with RSS (v 0.9x, 2.x, 1.0) + Atom feeds.
https://github.com/haskell-party/feed
LTS Haskell 22.9: | 1.3.2.1@rev:2 |
Stackage Nightly 2024-09-07: | 1.3.2.1@rev:4 |
Latest on Hackage: | 1.3.2.1@rev:4 |
feed-1.3.2.1@sha256:be3e09df396a205edfaffd6f60f2e8ff6531e360e0f6f56a25f3f662e76413c6,4721
Module documentation for 1.3.2.1
- Text
- Text.Atom
- Text.DublinCore
- Text.Feed
- Text.RSS
- Text.RSS1
Feed
Goal
Interfacing with RSS (v 0.9x, 2.x, 1.0) + Atom feeds.
- Parsers
- Constructors
- Rendering
- Querying
To help working with the multiple feed formats we’ve ended up with this set of modules providing parsers, printers and some utility code for querying and just generally working with a concrete representation of feeds in Haskell.
For basic reading and editing of feeds, consult the documentation of the Text.Feed.* hierarchy.
Usage
Building an Atom feed is similar to building an RSS feed, but we’ll arbitrarily pick Atom here:
We’d like to generate the XML for a minimal working example.
Constructing our base Feed
can use the smart constructor called nullFeed
:
This is a pattern the library maintains for smart constructors. If you want the minimum viable ‘X’, use the ‘nullX’ constructor.
{-# LANGUAGE OverloadedStrings #-}
module Main where
import Prelude.Compat hiding (take)
import Data.Maybe
import Data.Text
import Data.XML.Types as XML
import qualified Data.Text.Lazy as Lazy
import Text.Feed.Types
import Text.XML (def, rsPretty)
import qualified Text.Atom.Feed as Atom
import qualified Text.Feed.Export as Export (textFeedWith)
myFeed :: Atom.Feed
myFeed = Atom.nullFeed
"http://example.com/atom.xml"
(Atom.TextString "Example Website")
"2017-08-01"
Now we can export the feed to Text
.
renderFeed :: Atom.Feed -> Lazy.Text
renderFeed = fromJust . Export.textFeedWith def{rsPretty = True} . AtomFeed
We can now render our feed:
-- |
-- $setup
-- >>> import qualified Data.Text.Lazy.IO as Lazy
--
-- >>> Lazy.putStr $ renderFeed myFeed
-- <?xml version="1.0" encoding="UTF-8"?>
-- <feed xmlns="http://www.w3.org/2005/Atom">
-- <title type="text">
-- Example Website
-- </title>
-- <id>
-- http://example.com/atom.xml
-- </id>
-- <updated>
-- 2017-08-01
-- </updated>
-- </feed>
The TextContent
sum type allows us to specify which type of text we’re providing.
data TextContent
= TextString Text
| HTMLString Text
| XHTMLString XML.Element
deriving (Show)
A feed isn’t very useful without some content though, so we’ll need to build up an Entry
.
data Post
= Post
{ _postedOn :: Text
, _url :: Text
, _content :: Text
}
examplePosts :: [Post]
examplePosts =
[ Post "2000-02-02T18:30:00Z" "http://example.com/2" "Bar."
, Post "2000-01-01T18:30:00Z" "http://example.com/1" "Foo."
]
Our Post
data type will need to be converted into an Entry
in order to use it in the top level Feed
. The required fields for an entry are an url “id” from which an entry’s presence can be validated, a title for the entry, and a posting date. In this example we’ll also add authors, link, and the entries actual content, since we have all of this available in the Post
provided.
toEntry :: Post -> Atom.Entry
toEntry (Post date url content) =
(Atom.nullEntry
url -- The ID field. Must be a link to validate.
(Atom.TextString (take 20 content)) -- Title
date)
{ Atom.entryAuthors = [Atom.nullPerson {Atom.personName = "J. Smith"}]
, Atom.entryLinks = [Atom.nullLink url]
, Atom.entryContent = Just (Atom.HTMLContent content)
}
From the base feed we created earlier, we can add further details (Link
and Entry
content) as well as map our toEntry
function over the posts we’d like to include in the feed.
feed :: Atom.Feed
feed =
myFeed { Atom.feedEntries = fmap toEntry examplePosts
, Atom.feedLinks = [Atom.nullLink "http://example.com/"]
}
-- |
-- >>> Lazy.putStr $ renderFeed feed
-- <?xml version="1.0" encoding="UTF-8"?>
-- <feed xmlns="http://www.w3.org/2005/Atom">
-- <title type="text">
-- Example Website
-- </title>
-- <id>
-- http://example.com/atom.xml
-- </id>
-- <updated>
-- 2017-08-01
-- </updated>
-- <link href="http://example.com/"/>
-- <entry>
-- <id>
-- http://example.com/2
-- </id>
-- <title type="text">
-- Bar.
-- </title>
-- <updated>
-- 2000-02-02T18:30:00Z
-- </updated>
-- <author>
-- <name>
-- J. Smith
-- </name>
-- </author>
-- <content type="html">
-- Bar.
-- </content>
-- <link href="http://example.com/2"/>
-- </entry>
-- <entry>
-- <id>
-- http://example.com/1
-- </id>
-- <title type="text">
-- Foo.
-- </title>
-- <updated>
-- 2000-01-01T18:30:00Z
-- </updated>
-- <author>
-- <name>
-- J. Smith
-- </name>
-- </author>
-- <content type="html">
-- Foo.
-- </content>
-- <link href="http://example.com/1"/>
-- </entry>
-- </feed>
See here for this content as an uninterrupted running example.
-- Dummy main needed to compile this file with markdown-unlit
main :: IO ()
main = return ()
Changes
1.3.2.1
- text 2.0 support, thanks to Alexander Batischev.
- Moved the repository to https://github.com/haskell-party/
1.3.2.0
- Expose RSS/Atom item content through queries by using
getItemContent
.
1.3.0.1
- Add a test to check that validation works on a simple entry.
- Change attribute handling when validating so that type attribute is recognised properly on content.
1.3.0.0
- Reverted changes to
EntryContent
that came in 1.2.0.0. Thanks to Tomas Janousek.
1.2.0.1
- Get rid of xmlns:ns and ns:-prefixed attributes that confused some applications, thanks to Tomas Janousek.
- GHC 8.8 support
1.2.0.0
Updated EntryContent
’s HTMLContent
to wrap an XML.Element
instead of Text
. Thanks to Jake Keuhlen.
1.1.0.0
parseFeedFromFile
now returnsIO (Maybe Feed)
instead ofIO Feed
to distinguish IO exceptions from parse failures. Thanks to Jake Keuhlen.
1.0.1.0
-
Support for GHC 8.6.x libraries
-
Add
textFeed
andtextRSS
helpers (thanks to Francesco Ariis)
1.0.0.0
- Thanks to Dmitry Dzhus feed has been modernized to use the
text
,xml-types
andxml-conduit
libraries.
0.3.12.0
- Adds support for some fallback parsing of atom feeds to XMLFeed (thanks to Joey Hess)
0.3.11.1
- Add missing file to dist of test-suite (thanks to Sergei Trofimovich)
0.3.11.0
- Add
toFeedDateStringUTC
which uses UTCTime rather than ClockTime (thanks to Emanuel Borsboom) - Now with explicit export lists!
0.3.10.4
- Fix toFeedDateString time format, It used %s (seconds since epoch) instead of %S (seconds of minute), and %m (month) instead of %M (minute) (thanks to Emanuel Borsboom)
0.3.10.3
- RSS Export: avoid attribute (thanks to Roman Cheplyaka)
0.3.10.2
- The Atom RFC says that when a link element doesn’t specify the “rel” attribute, i.e. link relation, it should be interpreted as an “alternate” relation. This makes the feed and item query functions treat a missing relation as “alternate”.
0.3.10.1
- Allow
HUnit 1.3.*
0.3.10.0
- Add
Text.Feed.Import.parseFeedSource :: XmlSource s => s -> Maybe Feed
(thanks to Dmitry Dzhus)
0.3.9.7
- Add missing modules in test-suite
0.3.9.6
- Fixed the “cloud” having attribute “register” instead of “registerProcedure”: https://validator.w3.org/feed/docs/rss2.html#ltcloudgtSubelementOfLtchannelgt (thanks to Daniele Francesconi)
0.3.9.5
- Fix typo “skipDayss” -> “skipDays” in
Text.RSS.Export
(thanks to Daniele Francesconi)
0.3.9.4
- Update maintainer information
- Add test suite
0.3.9.3
- Add support for utf8-string >= 1 && < 1.1 and time 1.5.*
0.3.9.1
- add ref to github repo + .cabal tidying.
0.3.9
- tidy up compilation with ghc-7.6(.3), bumped version (but no functional changes.)
0.3.8
- cabal build fixes.
0.3.7
- parsing: made be optional.
- parsing: try if is missing.