gurgitate-mail 1.10.0 → 1.10.1

data/lib/gurgitate-mail.rb

@@ -9,10 +9,61 @@ require 'gurgitate/mailmessage'
 require 'gurgitate/deliver'
 
 module Gurgitate
-    #========================================================================
-    # The actual gurgitator; reads a message and then it can do
-    # other stuff with it, like save to a mailbox or forward
+    # This is the actual gurgitator; it reads a message and then it can
+    # do other stuff with it, like saving it to a mailbox or forwarding
     # it somewhere else.
+    #
+    # To set configuration parameters for gurgitate-mail, use a keyword-
+    # based system.  It's almost like an attribute, only if you give the
+    # accessor a parameter, it will set the configuration parameter to
+    # the parameter's value.  For instance:
+    #
+    #  maildir "#{homedir}/Mail"
+    #  sendmail "/usr/sbin/sendmail"
+    #  spoolfile "Maildir"
+    #  spooldir homedir
+    #
+    # (This is because of an oddity in Ruby where, even if an
+    # accessor exists in the current object, if you say:
+    #    name = value
+    # it'll always create a local variable.  Not quite what you
+    # want when you're trying to set a config parameter.  You have
+    # to say <code>self.name = value</code>, which [I think] is ugly.
+    #
+    # In the interests of promoting harmony, of course,
+    # <code>self.name = value</code> still works.)
+    #
+    # The attributes you can define are:
+    #
+    # homedir ::  Your home directory.  This defaults to what your
+    #             actual home directory is.
+    #
+    # maildir :: The directory you store your mail in.  This defaults
+    #            to the "Mail" directory in your home dir.
+    #
+    # logfile :: The path to your gurgitate-mail log file.  If you
+    #            set this to +nil+, gurgitate-mail won't log anything.
+    #            The default value is ".gurgitate.log" in your home
+    #            directory.
+    #
+    # The following parameters are more likely to be interesting to the
+    # system administrator than the everyday user.
+    #
+    # sendmail :: The full path of your "sendmail" program, or at least
+    #             a program that provides functionality equivalent to
+    #             sendmail.
+    #
+    # spoolfile :: The default location to store mail messages, for the
+    #              messages that have been unaffected by your gurgitate
+    #              rules.  If an exception is raised by your rules, the
+    #              message will be delivered to the spoolfile.
+    #
+    # spooldir :: The location where users' system mail boxes live.
+    #
+    # folderstyle :: The style of mailbox to create (and to expect,
+    #                although gurgitate-mail automatically detects the
+    #                type of existing mailboxes).  See the separate
+    #                documentation for folderstyle for more details.
     class Gurgitate < Mailmessage
         include Deliver
 
@@ -36,7 +87,7 @@ module Gurgitate
         # syntax will continue to work.
         def self.attr_configparam(*syms)
             syms.each do |sym|
-                class_eval %/
+                class_eval %{
                     def #{sym} (*vals)
                         if vals.length == 1
                             @#{sym} = vals[0]
@@ -53,7 +104,7 @@ module Gurgitate
                     # old-style accessors though.  Breaking people's
                     # .gurgitate-rules is a bad idea.
                     attr_writer :#{sym}
-                /
+                }
             end
         end
 
@@ -78,7 +129,36 @@ module Gurgitate
         # What kind of mailboxes you prefer
         # attr_configparam :folderstyle
 
-        # What kind of mailboxes you prefer
+        # What kind of mailboxes you prefer.  Treat this like a
+        # configuration parameter.  If no argument is given, then
+        # return the current default type.
+        #
+        # Depending on what you set this to, some other configuration
+        # parameters change.  You can set this to the following things:
+        #
+        # <code>Maildir</code> :: Create Maildir mailboxes.
+        #
+        #                         This sets +spooldir+ to your home
+        #                         directory, +spoolfile+ to
+        #                         $HOME/Maildir and creates
+        #                         mail folders underneath that.
+        #
+        # <code>MH</code> :: Create MH mail boxes.
+        #
+        #                    This reads your <code>.mh_profile</code>
+        #                    file to find out where you've told MH to
+        #                    find its mail folders, and uses that value.
+        #                    If it can't find that in your .mh_profile,
+        #                    it will assume you want mailboxes in
+        #                    $HOME/Mail.  It sets +spoolfile+ to
+        #                    "inbox" in your mail directory.
+        #
+        # <code>Mbox</code> :: Create +mbox+ mailboxes.
+        #
+        #                      This sets +spooldir+ to
+        #                      <code>/var/spool/mail</code> and
+        #                      +spoolfile+ to a file with your username
+        #                      in <code>/var/spool/mail</code>.
         def folderstyle(*style)
             if style.length == 0 then
                 @folderstyle
@@ -141,7 +221,7 @@ module Gurgitate
             instance_eval(&block) if block_given?
         end
 
-        def add_rules(filename, options = {})
+        def add_rules(filename, options = {}) #:nodoc:
             if not Hash === options
                 raise ArgumentError.new("Expected hash of options")
             end
@@ -171,15 +251,16 @@ module Gurgitate
             end
         end
 
-        # Deletes the current message.
+        # Deletes (discards) the current message.
         def delete
             # Well, nothing here, really.
         end
 
-        # This is a neat one.  You can get any header as a method.
-        # Say, if you want the header "X-Face", then you call
-        # x_face and that gets it for you.  It raises NameError if
-        # that header isn't found.
+        # This is kind of neat.  You can get a header by calling its
+        # name as a method.  For example, if you want the header
+        # "X-Face", then you call x_face and that gets it for you.  It
+        # raises NameError if that header isn't found.
+        #
         # meth::
         #   The method that the caller tried to call which isn't
         #   handled any other way.
@@ -193,6 +274,7 @@ module Gurgitate
         end
 
         # Forwards the message to +address+.
+        #
         # address::
         #   A valid email address to forward the message to.
         def forward(address)
@@ -204,7 +286,7 @@ module Gurgitate
 
         # Writes +message+ to the log file.
         def log(message)
-            if(@logfile)then
+            if @logfile then
                 File.open(@logfile,"a") do |f|
                     f.flock(File::LOCK_EX)
                     f.print(Time.new.to_s+" "+message+"\n")
@@ -225,6 +307,17 @@ module Gurgitate
 
         # Pipes the message through +program+, and returns another
         # +Gurgitate+ object containing the output of the filter
+        #
+        # Use it like this:
+        #
+        #  filter "bogofilter -p" do
+        #    if x_bogosity =~ /Spam/ then
+        #      log "Found spam"
+        #      delete
+        #      return
+        #    end
+        #  end
+        #
         def filter(program,&block)
             self.log "Filtering with "+program
             IO.popen("-","w+") do |filter|
@@ -255,8 +348,7 @@ module Gurgitate
             end
         end
 
-        # Processes your .gurgitate-rules.rb.
-        def process(&block)
+        def process(&block) #:nodoc:
             begin
                 if @rules.size > 0 or block
                     @rules.each do |configfilespec|

data/lib/gurgitate/deliver/maildir.rb

@@ -15,7 +15,7 @@ module Gurgitate
             #   message to.  If it is of the form "=mailbox", it saves
             #   the message to +Maildir+/+mailbox+.  Otherwise, it
             #   simply saves the message to the file +mailbox+.
-            def self::check_mailbox(mailbox)
+            def self::check_mailbox mailbox
                 begin
                     if File.stat(mailbox).directory? then
                         if File.stat(File.join(mailbox,"cur")).directory? then
@@ -33,7 +33,7 @@ module Gurgitate
             #   One of "+mailbox+/tmp" or "+mailbox+/new", but that's
             #   only because that's what the maildir spec
             #   (http://cr.yp.to/proto/maildir.html) says.
-            def maildir_getfilename(dir)
+            def maildir_getfilename dir
                 time=Time.now.to_f
                 counter=0
                 hostname=Socket::gethostname
@@ -50,7 +50,7 @@ module Gurgitate
             # Creates a new Maildir folder +mailbox+
             # mailbox::
             #   The full path of the new folder to be created
-            def make_mailbox(mailbox)
+            def make_mailbox mailbox
                 Dir.mkdir(mailbox)
                 %w{cur tmp new}.each do |dir|
                     Dir.mkdir(File.join(mailbox,dir))
@@ -63,7 +63,7 @@ module Gurgitate
             #   message to.  If it is of the form "=mailbox", it saves
             #   the message to +Maildir+/+mailbox+.  Otherwise, it
             #   simply saves the message to the file +mailbox+.
-            def deliver_message(mailbox)
+            def deliver_message mailbox
                 begin
                     File.stat(mailbox)
                 rescue Errno::ENOENT

data/lib/gurgitate/deliver/mbox.rb

@@ -13,10 +13,10 @@ module Gurgitate
             #   the message to.  If it is of the form "=mailbox", it
             #   saves the message to +Maildir+/+mailbox+.  Otherwise,
             #   it simply saves the message to the file +mailbox+.
-            def self::check_mailbox(mailbox)
+            def self::check_mailbox mailbox
 
                 begin
-                    if File.stat(mailbox).file? then 
+                    if File.stat(mailbox).file? then
                         return MBox
                     else
                         return nil
@@ -32,9 +32,9 @@ module Gurgitate
             #   the message to.  If it is of the form "=mailbox", it
             #   saves the message to +Maildir+/+mailbox+.  Otherwise,
             #   it simply saves the message to the file +mailbox+.
-            def deliver_message(mailbox) 
-                File.open(mailbox,File::WRONLY | 
-                                  File::APPEND | 
+            def deliver_message mailbox
+                File.open(mailbox,File::WRONLY |
+                                  File::APPEND |
                                   File::CREAT) do |f|
                     f.flock(File::LOCK_EX)
                     message=(if f.stat.size > 0 then "\n" else "" end) + to_mbox

data/lib/gurgitate/deliver/mh.rb

@@ -15,7 +15,7 @@ module Gurgitate
             #   the message to.  If it is of the form "=mailbox", it
             #   saves the message to +Maildir+/+mailbox+.  Otherwise,
             #   it simply saves the message to the file +mailbox+.
-            def self::check_mailbox(mailbox)
+            def self::check_mailbox mailbox
                 begin
                     # Rather annoyingly, pretty well any directory can
                     # be a MH mailbox, but this just checks to make sure
@@ -24,10 +24,10 @@ module Gurgitate
                     # I could put in a check for the path given in
                     # $HOME/.mh_profile, but Claws-Mail uses MH mailboxes and
                     # disregards $HOME/.mh_profile.
-                    if File.stat(mailbox).directory? and 
-                        not ( File.exists?(File.join(mailbox, "cur")) or 
-                              File.exists?(File.join(mailbox, "tmp")) or 
-                              File.exists?(File.join(mailbox, "new"))) then 
+                    if File.stat(mailbox).directory? and
+                        not ( File.exists?(File.join(mailbox, "cur")) or
+                              File.exists?(File.join(mailbox, "tmp")) or
+                              File.exists?(File.join(mailbox, "new"))) then
                         return MH
                     end
                 rescue Errno::ENOENT
@@ -41,7 +41,7 @@ module Gurgitate
             #   the message to.  If it is of the form "=mailbox", it
             #   saves the message to +Maildir+/+mailbox+.  Otherwise,
             #   it simply saves the message to the file +mailbox+.
-            def deliver_message(mailbox) 
+            def deliver_message mailbox
                 if ! File.exists? mailbox then
                     Dir.mkdir(mailbox)
                 end
@@ -59,16 +59,16 @@ module Gurgitate
 
             private
 
-            def update_sequences(mailbox, msgnum)
+            def update_sequences mailbox, msgnum
                 sequences = File.join(mailbox, ".mh_sequences")
                 lockfile = sequences + ".lock" # how quaint
                 loop do
                     begin
-                        File.open(lockfile, 
-                                  File::WRONLY | 
-                                  File::CREAT | 
+                        File.open(lockfile,
+                                  File::WRONLY |
+                                  File::CREAT |
                                   File::EXCL ) do |lock|
-                            File.open(sequences, 
+                            File.open(sequences,
                                       File::RDWR | File::CREAT) do |seq|
 
                                 seq.flock(File::LOCK_EX)
@@ -91,7 +91,7 @@ module Gurgitate
                     rescue Errno::EEXIST
                         # some other process is doing something, so wait a few
                         # milliseconds until it's done
-                        sleep(0.01) 
+                        sleep(0.01)
                     end
                 end
             end
@@ -115,13 +115,13 @@ module Gurgitate
                 end
             end
 
-            def next_message(mailbox)
+            def next_message mailbox
                 next_msgnum = Dir.open(mailbox).map { |ent| ent.to_i }.max + 1
                 loop do
                     begin
                         File.open(File.join(mailbox, next_msgnum.to_s),
-                                  File::WRONLY | 
-                                  File::CREAT | 
+                                  File::WRONLY |
+                                  File::CREAT |
                                   File::EXCL ) do |filehandle|
                             yield filehandle
                         end

data/lib/gurgitate/headers.rb

@@ -22,7 +22,7 @@ module Gurgitate
         
         def sub(regex, replacement)
             ::Gurgitate::HeaderBag.new(
-                self.map do |header|
+                clone.map do |header|
                     ::Gurgitate::Header.new(
                         "#{header.name}: " + header.contents.sub(regex, 
                                                                  replacement)
@@ -47,7 +47,7 @@ module Gurgitate
         # Figures out whether the first line of a mail message is an
         # mbox-style "From " line (say, if you get this from sendmail),
         # or whether it's just a normal header.
-        # -- 
+        # --
         # If you run "fetchmail" with the -m option to feed the
         # mail message straight to gurgitate, skipping the "local
         # MTA" step, then it doesn't have a "From " line.  So I
@@ -121,7 +121,8 @@ module Gurgitate
                     @from=$+
                 end
             else
-                fromregex=/([^ ]+@[^ ]+) \(.*\)|[^<]*[<](.*@.*)[>]|([^ ]+@[^ ]+)/
+                fromregex=/([^ ]+@[^ ]+) \(.*\)|[^<]*[<](.*@.*)[>]|([^ ]+@[^ ]+
+)/
                 if self["Return-Path"] != nil then
                     fromregex.match(self["Return-Path"][0].contents)
                 else
@@ -135,12 +136,14 @@ module Gurgitate
                 # assume that it's local mail, and doesn't have an @ in its
                 # address.
                 unless address_candidate
-                    if self["Return-Path"] != nil then
+                    if self["Return-Path"] then
                         self["Return-Path"][0].contents =~ /(\S+)/
                         address_candidate=$+
                     else
-                        self["From"][0].contents =~ /(\S+)/
-                        address_candidate=$+
+                        if self["From"] then
+                            self["From"][0].contents =~ /(\S+)/
+                                address_candidate=$+
+                        end
                     end
                 end
 
@@ -222,7 +225,7 @@ module Gurgitate
         # Change the envelope from line to whatever you want.  This might
         # not be particularly neighborly, but oh well.
         # newfrom:: An email address
-        def from=(newfrom) 
+        def from=(newfrom)
             @from=newfrom
             @unix_from="From "+self.from+" "+Time.new.to_s
         end

data/lib/gurgitate/mail_headers.rb

@@ -0,0 +1,166 @@
+#!/opt/bin/ruby -w
+
+require "gurgitate/headers"
+
+module Gurgitate
+    class IllegalHeader < RuntimeError ; end
+
+# ========================================================================
+
+    # A slightly bigger class for all of a message's headers
+    class MailHeaders < Headers
+
+        private
+
+        # Figures out whether the first line of a mail message is an
+        # mbox-style "From " line (say, if you get this from sendmail),
+        # or whether it's just a normal header.
+        # -- 
+        # If you run "fetchmail" with the -m option to feed the
+        # mail message straight to gurgitate, skipping the "local
+        # MTA" step, then it doesn't have a "From " line.  So I
+        # have to deal with that by hand.  First, check to see if
+        # there's a "From " line present in the first place.
+        def figure_out_from_line(headertext)
+            (unix_from,normal_headers)  = headertext.split(/\n/,2)
+
+            if unix_from =~ /^From /  then
+                headertext=normal_headers
+                unix_from=unix_from
+            else
+                # If there isn't, then deal with it after we've
+                # worried about the rest of the headers, 'cos we'll
+                # have to make our own.
+                unix_from=nil
+            end
+            return unix_from, headertext
+        end
+
+        # Get the envelope From information.  This comes with a
+        # whole category of rants: this information is absurdly hard
+        # to get your hands on.  The best you can manage is a sort
+        # of educated guess.  Thus, this horrible glob of hackiness.
+        # I don't recommend looking too closely at this code if you
+        # can avoid it, and further I recommend making sure to
+        # configure your MTA so that it sends proper sender and
+        # recipient information to gurgitate so that this code never
+        # has to be run at all.
+        def guess_sender
+            # Start by worrying about the "From foo@bar" line.  If it's
+            # not there, then make one up from the Return-Path: header.
+            # If there isn't a "Return-Path:" header (then I suspect we
+            # have bigger problems, but still) then use From: as a wild
+            # guess.  If I hope that this entire lot of code doesn't get
+            # used, then I _particularly_ hope that things never get so
+            # bad that poor gurgitate has to use the From: header as a
+            # source of authoritative information on anything.
+            #
+            # And then after all that fuss, if we're delivering to a
+            # Maildir, I have to get rid of it.  And sometimes the MTA
+            # gives me a mbox-style From line and sometimes it doesn't.
+            # It's annoying, but I have no choice but to Just Deal With
+            # It.
+            if @unix_from then
+                # If it is there, then grab the email address in it and
+                # use that as our official "from".
+                fromregex=/^From ([^ ]+@[^ ]+) /
+                fromregex.match(@unix_from)
+                @from=$+
+
+                # or maybe it's local
+                if @from == nil then
+                    @unix_from =~ /^From (\S+) /
+                    @from=$+
+                end
+            else
+                fromregex=/([^ ]+@[^ ]+) \(.*\)|[^<]*[<](.*@.*)[>]|([^ ]+@[^ ]+)/
+                if self["Return-Path"] != nil then
+                    fromregex.match(self["Return-Path"][0].contents)
+                else
+                    if self["From"] != nil then
+                        fromregex.match(self["From"][0].contents)
+                    end
+                end
+                address_candidate=$+
+
+                # If there STILL isn't a match, then it's probably safe to
+                # assume that it's local mail, and doesn't have an @ in its
+                # address.
+                unless address_candidate
+                    if self["Return-Path"] != nil then
+                        self["Return-Path"][0].contents =~ /(\S+)/
+                        address_candidate=$+
+                    else
+                        self["From"][0].contents =~ /(\S+)/
+                        address_candidate=$+
+                    end
+                end
+
+                @from=address_candidate
+
+                @unix_from="From "+self.from+" "+Time.new.to_s
+            end
+        end
+
+        public
+
+        # Creates a MailHeaders object.
+        # headertext::
+        #   The text of the message headers.
+        def initialize(headertext=nil, sender=nil, recipient=nil)
+            @from    = sender
+            @to      = recipient
+            @headers = Hash.new(nil)
+
+            if Hash === headertext
+                @headers_changed = true
+                headertext.each_key do |key|
+
+                    headername = key.to_s.gsub("_","-")
+
+                    header=Header.new(headername, headertext[key])
+                    @headers[header.name] ||= HeaderBag.new
+                    @headers[header.name].push(header)
+                end
+            else
+                if headertext
+                    @unix_from, @headertext = figure_out_from_line headertext
+                    parse_headers if @headertext
+
+                    if sender # then don't believe the mbox separator
+                        @from = sender
+                        @unix_from="From "+self.from+" "+Time.new.to_s
+                    else
+                        guess_sender
+                    end
+                end
+            end
+        end
+
+        # Who the message is to (the envelope to)
+        #
+        # Yet another bucket of rants.  Unix mail sucks.
+        def to
+            return @to || @headers["X-Original-To"] || nil
+        end
+
+        # Who the message is from (the envelope from)
+        def from
+            return @from || ""
+        end
+
+        # Change the envelope from line to whatever you want.  This might
+        # not be particularly neighborly, but oh well.
+        # newfrom:: An email address
+        def from=(newfrom) 
+            @from=newfrom
+            @unix_from="From "+self.from+" "+Time.new.to_s
+        end
+
+        # Returns the headers properly formatted for an mbox-format
+        # email message.
+        def to_mbox
+            return @unix_from+"\n"+to_s
+        end
+    end
+end