Intro

This module allows you to run a loop which visits web feeds (RSS, Atom, etc.) periodically and reports new items using a function you provide. You can also insert control commands into the loop, such as adding and removing a feed, so that stopping and restarting it isn't required.

Both http and https URLs are supported.

The original use case which motivated the creation of this library is FunBot.

Running

The run function runs the loop, and it takes a collector callback function (as one of its parameters) to be called when new feed items are found.

Here is a simple usage example.

import Data.Time.Units
import Web.Feed.Collect

collect :: Label -> URL -> Feed -> Item -> IO ()
collect label url feed item = do
    putStrLn $ label ++ " : " ++ url
    putStrLn "Got a new feed item!"
    putStrLn $ showFeed feed
    putStrLn $ showItem item

logError :: Error -> IO ()
logError = print

feeds :: [(Label, Url)]
feeds = [("democ-now", "http://www.democracynow.org/democracynow.rss")]

main :: IO ()
main = run collect Nothing logError Nothing (1 :: Minute) 3 feeds

For quick testing, you can use one of the predefined collector functions. For example, there is collectorNull which discards the feed items and does nothing (you can use it e.g. when testing success of HTTP requests or debugging the library itself), and collectorPretty which writes a short nicely formatted entry to stdout for each new feed item. And there are more.

If new items aren't being detected correctly, you can try using runDebug in place of run. It takes and same arguments and runs the same loop, but also writes a detailed log of the detection process into a file "debug.log". You can use tail -f debug.log from your terminal to watch new log entries get appended to the file.

Using Control Commands

Now let's see how to push control commands into the loop. The 4th parameter run takes is an optional command queue. In the example above we just passed Nothing. Now let's provide an actual queue and use it.

Suppose we are writing a program with a command-line interface. It watches news feeds in the background, and can take commands from the user at the same time on the command-line. Feeds can be added, removed, etc. without restarting the program.

Assume we've written a function named parseCommand, which takes a line of user input and returns a command ready to push into the queue. The parsed commands are of type Command and are created using functions like addFeed, removeFeed and so on, which this module provides. Using our parseCommand we can write the program like this:

import Control.Concurrent (forkIO)
import Data.Time.Units
import System.IO
import Web.Feed.Collect

collect :: Label -> URL -> Feed -> Item -> IO ()
collect = collectPretty

logE :: Error -> IO ()
logE = print

feeds :: [(Label, Url)]
feeds = [("fsf-news", "https://www.fsf.org/static/fsforg/rss/news.xml")]

parseCommand :: String -> Maybe Command
parseCommand line = {- ... - }

main :: IO ()
main = do
    cqueue <- newCommandQueue
    forkIO $ run collect Nothing logE (Just cqueue) (1 :: Minute) 3 feeds
    let loop = do
        line <- getLine
        if line == "quit"
            then putStrLn "Bye!"
            else do
                case parseCommand line of
                    Just cmd -> sendCommand cqueue cmd
                    Nothing  -> putStrLn "Invalid input"
                loop
    loop