Replace output_filter and output_sort with output_sort_articles.

The new hook has a more sensible interface, too: plugins can avoid the
default sort if they want.

diff --git a/NEWS b/NEWS
index 78db6efe4783b9cbc16b46ca968904a155668c68..f3da16f34f583fb2c6e87a053ffb6c3d6fd1b731 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,3 @@
-FIXME: either fix or remove the sort/filter hooks, and document what
-their replacements are.
-
 - rawdog 2.12
 
 Update feedparser to revision 291, which fixes the handling of
@@ -12,8 +9,13 @@ Add the "splitstate" option, which makes rawdog use a separate state
 file for each feed rather than one large one. This significantly reduces
 rawdog's memory usage at the cost of some more disk IO during --write.
 The old behaviour is still the default, but I would recommend turning
-splitstate on if you read a lot of feeds or if you're on a machine with
-limited memory.
+splitstate on if you read a lot of feeds, if you use a long expiry time,
+or if you're on a machine with limited memory.
+
+As a result of the splitstate work, the output_filter and output_sort
+hooks have been removed (because there's no longer a complete list of
+articles to work with). Instead, there's now an output_sort_articles
+hook that works with a list of article summaries.
 
 Add the "useids" option, which makes rawdog respect article GUIDs when
 updating feeds; if an article's GUID matches one we already know about,

diff --git a/PLUGINS b/PLUGINS
index 18d9757a0ab6556c3fef899cf8a23096bfd632f6..694f0b3484665bf02dc2d1e9ab912e0ea6a3751e 100644 (file)
--- a/PLUGINS
+++ b/PLUGINS
@@ -94,20 +94,18 @@ As config_option for options that can handle extra argument lines.
 If the options you are implementing should not have extra arguments,
 then use the config_option hook instead.
 
-### output_filter(rawdog, config, articles)
+### output_sort_articles(rawdog, config, articles)
 
-* articles: the mutable list of Article objects
-
-Called before rawdog sorts the list of articles to write. This hook can
-be used to remove articles that shouldn't be written.
+* articles: the mutable list of (date, feed_url, sequence_number,
+  article_hash) tuples
 
-### output_sort(rawdog, config, articles)
-
-* articles: the mutable list of Article objects
+Called to sort the list of articles to write. The default action here is
+to just call the list's sort method; if you sort the list in a different
+way, you should return False from this hook to prevent rawdog from
+resorting it afterwards.
 
-Called after rawdog has sorted the list of articles to write. This hook
-can be used to reorder (or completely resort) the list of articles to
-write.
+Later versions of rawdog may add more items at the end of the tuple;
+bear this in mind when you're manipulating the items.
 
 ### output_write(rawdog, config, articles)
 
@@ -296,6 +294,14 @@ Called after feedparser has been called to fetch the feed. This hook can
 be used to manipulate the received feed data or implement custom error
 handling.
 
+## Obsolete hooks
+
+The following hooks existed in previous versions of rawdog, but are no
+longer supported:
+
+* output_filter (since rawdog 2.12); use output_sorted_filter instead
+* output_sort (since rawdog 2.12); use output_sort_articles instead
+
 ## Examples
 
 ### backwards.py
@@ -306,10 +312,11 @@ sort order of the output.
        import rawdoglib.plugins
        
        def backwards(rawdog, config, articles):
+               articles.sort()
                articles.reverse()
                return False
        
-       rawdoglib.plugins.attach_hook("output_sort", backwards)
+       rawdoglib.plugins.attach_hook("output_sort_articles", backwards)
 
 ### option.py
 

diff --git a/rawdoglib/rawdog.py b/rawdoglib/rawdog.py
index dc36ded94b8c6be44ad1621598e97bfcf1b654cb..1569f574eb2bdaed905e34bf25f45c2cf99360e4 100644 (file)
--- a/rawdoglib/rawdog.py
+++ b/rawdoglib/rawdog.py
@@ -1,5 +1,5 @@
 # rawdog: RSS aggregator without delusions of grandeur.
-# Copyright 2003, 2004, 2005, 2006, 2007, 2008 Adam Sampson <ats@offog.org>
+# Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2009 Adam Sampson <ats@offog.org>
 #
 # rawdog is free software; you can redistribute and/or modify it
 # under the terms of that license as published by the Free Software
@@ -1481,9 +1481,8 @@ __description__
                        article_list = list_articles(self.articles)
                numarticles = len(article_list)
 
-               # FIXME call output_filter
-               article_list.sort()
-               # FIXME call output_sort
+               if not plugins.call_hook("output_sort_articles", self, config, article_list):
+                       article_list.sort()
 
                if config["maxarticles"] != 0:
                        article_list = article_list[:config["maxarticles"]]