From: Adam Sampson <ats@offog.org>
Date: Tue, 27 Jan 2009 21:21:52 +0000 (+0000)
Subject: Replace output_filter and output_sort with output_sort_articles.
X-Git-Tag: v2.12rc1^0
X-Git-Url: http://git.ozo.com/?a=commitdiff_plain;h=50f87261202fe86b44f841e2e96120bee79dd0be;p=rawdog%2F.git

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 78db6ef..f3da16f 100644
--- 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 18d9757..694f0b3 100644
--- 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 dc36ded..1569f57 100644
--- 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"]]