use FileHandle and set autoflush on STDOUT since the new spam checking

is so fast the status reporting is now funky without autoflushing.

Document spam_check, spam_start_hook, spam_stop_hook.

My trick for defining is_spam() was broken and i never noticed because
i wasn't doing use strict in .mincspam; fix it with eval and also add
spam_start_hook and spam_stop_hook.

(kill_spam): Now call spam_start_hook(), save the list it returns, and
pass it to each spam_check() call (formerly known as is_spam()).  Also
pass it to spam_stop_hook() after processing all spam.  This allows
the spam processor to maintain state, and do other things like talk to
a co-process.

diff --git a/minc b/minc
index 52e9a82..79a85e2 100755 (executable)
--- a/minc
+++ b/minc
@@ -31,12 +31,16 @@ require 'sysexits.ph';
 use Data::Dumper;
 use Errno;
 use Fcntl qw(O_WRONLY O_EXCL O_CREAT);
+use FileHandle;
 use File::Basename;
 use Getopt::Std;
 use Log::Dispatch;
 use Log::Dispatch::File;
 use POSIX qw(strftime WEXITSTATUS WIFEXITED);
 
+# Autoflush STDOUT for the benefit of the status reporting in kill_spam().
+STDOUT->autoflush(1);
+
 # If a filter set's header is $MAGIC_TO_TOKEN, that set is compared
 # against headers matching this regex (taken from procmail).
 my $MAGIC_TO_REGEX = '^((Original-)?(Resent-)?(To|Cc|Bcc)|(X-Envelope |Apparently(-Resent)?)-To)';
@@ -140,16 +144,23 @@ expected to define the FILTERS list.
 
 =item $HOME/.mincspam
 
-If this file exists, B<minc> will include it with the expectation that it
-will define a B<is_spam> function.  This function takes a message
-filename as an argument and returns 1 if the message is spam, else 0.
-If this file does not exist, B<minc> will define a simple function that
-always returns 0.
+If this file exists, B<minc> will include it with the expectation that
+it will define a B<spam_check> function.  This function takes a
+message filename as an argument and returns 1 if the message is spam,
+else 0.  If this file does not exist, B<minc> will define a simple
+function that always returns 0.
 
 One of B<minc>'s global variables is available to the user-defined
-is_spam function: $run.  This boolean should be honored; is_spam
-should only take real action (i.e. removing or creating files, running
-external programs, etc.) if $run is non-zero.
+B<spam_check> function: $run.  This boolean should be honored;
+B<spam_check> should only take real action (i.e. removing or creating
+files, running external programs, etc.) if $run is non-zero.
+
+This file may also declare two other functions: B<spam_start_hook> and
+B<spam_stop_hook>.  The former is passed no arguments and is expected
+to return a list.  This list is a "baton" that will also be passed to
+B<spam_check> and B<spam_stop_hook>.  It can hold anything
+B<spam_check> will need to do its job, whether network sockets, pipes,
+or whatever.
 
 XXX: need more details about the spam-handling process; for now read
 the code.
@@ -183,9 +194,9 @@ require "$HOME/.mincfilter";
 if (-f "$HOME/.mincspam") {
     require "$HOME/.mincspam";
 } else {
-    sub is_spam {
-        return 0;
-    }
+    eval "sub spam_start_hook { return (); }";
+    eval "sub spam_stop_hook { }";
+    eval "sub spam_check { return 0; }";
 }
 
 my $mh;
@@ -544,18 +555,20 @@ sub get_headers {
 # Spam handling
 
 sub kill_spam {
+    my @baton;
     my @msglist = @_;
     my @result;
     my $msg;
     my $i;
 
-    @result = ();
+    @baton = spam_start_hook();
 
+    @result = ();
     $i = 0;
     foreach $msg (@msglist) {
         printf('%sChecking for spam... %6d/%d',
                "\r", ++$i, scalar(@msglist));
-        if (is_spam($msg)) {
+        if (spam_check($msg, @baton)) {
             print(" SPAM\n");
             store_message($msg, 'SPAM');
         } else {
@@ -564,6 +577,8 @@ sub kill_spam {
     }
     print("\nDone: ", scalar(@result), " survivors\n");
 
+    spam_stop_hook(@baton);
+
     return @result;
 }
 
@@ -735,7 +750,7 @@ apache.org subdomain, with mailing lists hosted there.  So, given a
 list such as dev@httpd.apache.org, this filter will create the folder
 name l/apache/httpd/dev.
 
-For an example is_spam function, see
+For an example B<spam_check> function, see
 L<http:E<047>E<047>pretzelnet.orgE<047>cvsE<047>dotfilesE<047>.mincspam>
 
 =head1 AUTHORS