hermeneutics 1.10 → 1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 721abdbe281ba643a27fefdcb8016c0f1a0202ed65e6c9741b5a90c3320c121e
-  data.tar.gz: c78e80af37ced64e8ab89d19b729da96f3b6d0e888f0bf0c5de96274bbdf30c3
+  metadata.gz: d06afea9e09641e4c0c05bc3fca3590c3b4002047092034a379ab9a096867a57
+  data.tar.gz: 21944a76c2279a66b7de8ea9d32ad6db9328898c7ff944a2b736e0c3500dd61c
 SHA512:
-  metadata.gz: 30f6297db18bab61106428eee10338bfe4907dae30fa12bfbff8dc3e94a931b349befc4f5fa65bd21c9b053d9c9e8904d8c7d9920fc2f63f51d393167dc13a0b
-  data.tar.gz: 9f96a1b60536b83254252029fa36fa3e7ed739f270799bd8ccd155e068407a4b31de0073bb7049c5306b7096f5c9b54dca7ba53f8564966f7e82e6830cc644f4
+  metadata.gz: 399dd807c48582880089a94580b1c939ad57fc5da148b9987dff1f77729e731b62863f2f44a8a7540aefc4edc9dd211ab8dfe5a759d654ab6f9de682c968f9e7
+  data.tar.gz: 61514f34f392828df42f4123e49c6d7af7aecaf0dd3a503241ee60d5ee811e5e8fecb957cebee7bca4a407afab656ce96922f5ebf7d6c683e584acc3c56bf70f

data/README

@@ -0,0 +1,11 @@
+= Hermeneutics
+
+Fast and easy CGI and mail handling using Ruby
+
+== Description
+
+I'm working with this library on several projects for over a decade and I am
+very happy with it.
+
+Yet, it is not documented very well.
+

data/bin/hermesmail

@@ -11,8 +11,7 @@ rescue LoadError
 end
 
 require "hermeneutics/version"
-require "hermeneutics/transports"
-require "hermeneutics/cli/pop"
+require "hermeneutics/mail"
 
 
 module Hermeneutics
@@ -38,7 +37,7 @@ module Hermeneutics
 
     # Forward by SMTP
     def forward_smtp to
-      send nil, to
+      send! nil, to
       done
     end
 
@@ -50,45 +49,26 @@ module Hermeneutics
     alias forward forward_smtp
 
 
-    self.logfile  = "hermesmail.log"
-    self.loglevel = :ERR
-
     @failed_process = "=failed-process"
+    @failed_parse   = "=failed-parse"
 
     class <<self
-      attr_accessor :failed_process
+      attr_accessor :failed_process, :failed_parse
       def process input, debug = false
         i = parse input
         i.debug = debug
         i.execute
       rescue
         raise if debug
-        open_failed { |f|
-          log_exception "Error while parsing mail", f.path
-          f.write input
-        }
+        log_exception "Error while parsing mail"
+        b = box @failed_parse
+        log :INF, "Saving to", b.path
+        b.store_raw input, nil, nil
       end
       def log_exception msg, *args
         log :ERR, "#{msg}: #$! (#{$!.class})", *args
         $!.backtrace.each { |b| log :INF, "    #{b}" }
       end
-      private
-      def open_failed
-        i = 0
-        d = expand_sysdir
-        w = Time.now.strftime "%Y%m%d%H%M%S"
-        begin
-          p = File.join d, "failed-#{w}-%05d" % i
-          File.open p, File::CREAT|File::EXCL|File::WRONLY do |f|
-            yield f
-          end
-        rescue Errno::ENOENT
-          Dir.mkdir! d and retry
-        rescue Errno::EEXIST
-          i +=1
-          retry
-        end
-      end
     end
 
     def execute
@@ -98,12 +78,12 @@ module Hermeneutics
     rescue
       raise if @debug
       log_exception "Error while processing mail"
-      b = cls.box cls.failed_process
+      b = self.class.box self.class.failed_process
       save b
     end
 
     def log_exception msg, *args
-      cls.log_exception msg, *args
+      self.class.log_exception msg, *args
     end
 
   end
@@ -112,44 +92,99 @@ module Hermeneutics
   class Fetch
 
     class <<self
+
       private :new
       def create *args, &block
-        i = new
-        i.instance_eval *args, &block
-        def i.each
-          @list.each { |a|
-            c = a[ :type].new *a[ :args]
-            a[ :logins].each { |l|
-              c.login *l do yield c end
-            }
-          }
-        end
-        i
+        @list = []
+        class_eval *args, &block
+        new @list
+      ensure
+        @list = nil
+      end
+
+      def pop *args, **kwargs
+        access Pop, *args, **kwargs do yield end
+      end
+      def login *args
+        @access[ :logins].push args
+        nil
+      end
+
+      private
+      def access type, *args, **kwargs
+        @access and raise "Access methods must not be nested."
+        @access = { type: type, args: args, kwargs: kwargs, logins: [] }
+        yield
+        @list.push @access
+        nil
+      ensure
+        @access = nil
       end
-    end
 
-    def initialize
-      @list = []
     end
 
-    def pop  *args ; access Cli::Pop,  *args do yield end ; end
-    def pops *args ; access Cli::Pops, *args do yield end ; end
+    def initialize list
+      @list = list
+    end
 
-    def login *args
-      @access[ :logins].push args
-      nil
+    def each
+      @list.each { |a|
+        c = a[ :type].new *a[ :args], **a[ :kwargs]
+        a[ :logins].each { |l|
+          c.login *l do yield c end
+        }
+      }
     end
 
+    class Keep < Exception ; end
+
     private
 
-    def access type, *args
-      @access and raise "Access methods must not be nested."
-      @access = { type: type, args: args, logins: [] }
-      yield
-      @list.push @access
-      nil
-    ensure
-      @access = nil
+
+    class Pop
+
+      def initialize host, port = nil, ssl: nil
+        if not port and host =~ /:(\d+)\z/ then
+          host, port = $`, $1.to_i
+        end
+        @host, @port, @ssl = host, port, ssl
+      end
+
+      def login user, password
+        require "hermeneutics/cli/pop3"
+        Cli::POP3.open @host, @port, ssl: @ssl do |pop|
+          @user, @password, @pop = user, password, pop
+          @pop.authenticate @user, @password
+          yield
+          @pop.quit
+        end
+      ensure
+        @user, @password, @pop = nil, nil, nil
+      end
+
+      def name
+        @user or raise "Not logged in."
+        r = "#@user@#@host"
+        r << ":#@port" if @port
+        r
+      end
+
+      def count
+        c, = @pop.stat
+        c
+      end
+
+      def each
+        @pop.list.each { |k,|
+          text = @pop.retr k
+          begin
+            yield text
+            @pop.dele k
+          rescue Keep
+          end
+        }
+      end
+
     end
 
   end
@@ -164,10 +199,10 @@ module Hermeneutics
     LICENSE   = Hermeneutics::LICENSE
     AUTHORS   = Hermeneutics::AUTHORS
 
-    DESCRIPTION = <<-EOT
-This mail delivery agent (MDA) reads a configuration file
-that is plain Ruby code. See the examples section for how
-to write one.
+    DESCRIPTION = <<~EOT
+      This mail delivery agent (MDA) reads a configuration file
+      that is plain Ruby code. See the examples section for how
+      to write one.
     EOT
 
     attr_accessor :rulesfile, :mbox, :fetchfile
@@ -231,7 +266,7 @@ to write one.
             print "\r#{i}/#{c}  " if @quiet < 1
             i += 1
             Processed.process m
-            raise Cli::Pop::Keep if @keep
+            raise Fetch::Keep if @keep
           }
           puts "\rDone.     " if @quiet < 1
         }

data/lib/hermeneutics/addrs.rb

@@ -95,8 +95,6 @@ module Hermeneutics
 
     end
 
-    attr_reader :mail, :real
-
     def initialize mail, real
       @mail, @real = mail, real
       @mail.compact!
@@ -138,6 +136,8 @@ module Hermeneutics
       tokenized.encode
     end
 
+    private
+
     def tokenized
       r = Token[ :addr, [ Token[ :lang] , @mail, Token[ :rang]]]
       if @real then
@@ -146,8 +146,6 @@ module Hermeneutics
       r
     end
 
-    private
-
     def mk_plain
       p = @mail.to_s
       p.downcase!
@@ -592,6 +590,9 @@ module Hermeneutics
 
     public
 
+    def empty?    ; @list.empty?            ; end
+    def notempty? ; self if @list.notempty? ; end
+
     def push addrs
       case addrs
         when nil    then
@@ -600,6 +601,7 @@ module Hermeneutics
         else             addrs.each { |a| push a }
       end
     end
+    alias << push
 
     def inspect
       "<#{self.class}: " + (@list.map { |a| a.inspect }.join ", ") + ">"

data/lib/hermeneutics/boxes.rb

@@ -4,7 +4,7 @@
 
 =begin rdoc
 
-:section: Classes definied here
+:section: Classes defined here
 
 Hermeneutics::Box is a general Mailbox.
 
@@ -18,7 +18,6 @@ Hermeneutics::Maildir is the maildir format.
 
 
 require "supplement"
-require "supplement/locked"
 require "date"
 
 
@@ -31,15 +30,18 @@ module Hermeneutics
 
     class <<self
 
+      attr_accessor :default_format
+
       # :call-seq:
       #   Box.find( path, default = nil)          -> box
       #
       # Create a Box object (some subclass of Box), depending on
-      # what type the box is found at <code>path</code>.
+      # what type the box is found at +path+.
       #
       def find path, default_format = nil
         b = @boxes.find { |b| b.check path }
         b ||= default_format
+        b ||= @default_format
         b ||= if File.directory? path then
           Maildir
         elsif File.file? path then
@@ -71,7 +73,7 @@ module Hermeneutics
     # :call-seq:
     #   Box.new( path)          -> box
     #
-    # Instantiate a Box object, just store the <code>path</code>.
+    # Instantiate a Box object, just store the +path+.
     #
     def initialize mailbox
       @mailbox = mailbox
@@ -84,12 +86,39 @@ module Hermeneutics
     # :call-seq:
     #   box.exists?     -> true or false
     #
-    # Test whether the <code>Box</code> exists.
+    # Test whether the +Box+ exists.
     #
     def exists?
       self.class.check @mailbox
     end
 
+    # :call-seq:
+    #   mbox.store( msg)     -> nil
+    #
+    # Store the mail to the local +MBox+.
+    #
+    def store msg
+      store_raw msg.to_s, msg.plain_from, msg.created
+    end
+
+    # :call-seq:
+    #   mbox.each { |mail| ... }    -> nil
+    #
+    # Iterate through +MBox+.
+    # Alias for +MBox#each_mail+.
+    #
+    def each &block ; each_mail &block ; end
+    include Enumerable
+
+    private
+
+    def local_from
+      require "etc"
+      require "socket"
+      s = File.stat @mailbox
+      lfrom = "#{(Etc.getpwuid s.uid).name}@#{Socket.gethostname}"
+    end
+
   end
 
   class MBox < Box
@@ -102,7 +131,7 @@ module Hermeneutics
       # :call-seq:
       #   MBox.check( path)     -> true or false
       #
-      # Check whether path is a <code>MBox</code>.
+      # Check whether path is a +MBox+.
       #
       def check path
         if File.file? path then
@@ -114,48 +143,10 @@ module Hermeneutics
 
     end
 
-    # :stopdoc:
-    class Region
-      class <<self
-        private :new
-        def open file, start, stop
-          t = file.tell
-          begin
-            i = new file, start, stop
-            yield i
-          ensure
-            file.seek t
-          end
-        end
-      end
-      def initialize file, start, stop
-        @file, @start, @stop = file, start, stop
-        rewind
-      end
-      def rewind ; @file.seek @start ; end
-      def read n = nil
-        m = @stop - @file.tell
-        n = m if not n or n > m
-        @file.read n
-      end
-      def to_s
-        rewind
-        read
-      end
-      def each_line
-        @file.each_line { |l|
-          break if @file.tell > @stop
-          yield l
-        }
-      end
-      alias eat_lines each_line
-    end
-    # :startdoc:
-
     # :call-seq:
     #   mbox.create     -> self
     #
-    # Create the <code>MBox</code>.
+    # Create the +MBox+.
     #
     def create
       d = File.dirname @mailbox
@@ -165,65 +156,69 @@ module Hermeneutics
     end
 
     # :call-seq:
-    #   mbox.deliver( msg)     -> nil
+    #   mbox.store_raw( text, from, created)     -> nil
     #
-    # Store the mail into the local <code>MBox</code>.
+    # Store some text that appears like a mail to the local +MBox+.
     #
-    def deliver msg
-      pos = nil
-      LockedFile.open @mailbox, "r+", encoding: Encoding::ASCII_8BIT do |f|
+    def store_raw text, from, created
+      from ||= local_from
+      created ||= Time.now
+      File.open @mailbox, "r+", encoding: Encoding::ASCII_8BIT do |f|
         f.seek [ f.size - 4, 0].max
-        last = ""
+        last = nil
         f.read.each_line { |l| last = l }
-        f.puts unless last =~ /^$/
-        pos = f.size
-        m = msg.to_s
-        i = 1
-        while (i = m.index RE_F, i rescue nil) do m.insert i, ">" end
-        f.write m
+        f.puts if last and not last =~ RE_N
+
+        f.puts "From #{from.gsub ' ', '_'} #{created.to_time.gmtime.asctime}"
+        text.each_line { |l|
+          l.chomp!
+          f.print ">" if l =~ RE_F
+          f.puts l
+        }
         f.puts
       end
-      pos
+      nil
     end
 
     # :call-seq:
-    #   mbox.each { |mail| ... }    -> nil
+    #   mbox.each_mail { |mail| ... }    -> nil
     #
-    # Iterate through <code>MBox</code>.
+    # Iterate through +MBox+.
     #
-    def each &block
+    def each_mail
       File.open @mailbox, encoding: Encoding::ASCII_8BIT do |f|
-        m, e = nil, true
-        s, t = t, f.tell
+        nl_seen = false
+        from, created, text = nil, nil, nil
         f.each_line { |l|
-          s, t = t, f.tell
-          if is_from_line? l and e then
+          l.chomp!
+          if l =~ RE_F then
+            l = $'
+            yield text, from, created if text
+            length_tried = false
+            from, created = l.split nil, 2
             begin
-              m and Region.open f, m, e, &block
-            ensure
-              m, e = s, nil
+              created = DateTime.parse created
+            rescue Date::Error
+              unless length_tried then
+                from = $'
+                created = from.slice! from.length-Time.now.ctime.length, from.length
+                from.strip!
+                length_tried = true
+                retry
+              end
+              raise "#@mailbox does not seem to be a mailbox: From line '#{l}'."
             end
+            text, nl_seen = "", false
           else
-            m or raise "#@mailbox does not seem to be a mailbox."
-            e = l =~ RE_N && s
+            from or raise "#@mailbox does not seem to be a mailbox. No 'From' line."
+            text << "\n" if nl_seen
+            nl_seen = l =~ RE_N
+            nl_seen or text << l << "\n"
           end
         }
-        # Treat it gracefully when there is no empty last line.
-        e ||= f.tell
-        m and Region.open f, m, e, &block
+        text and yield text, from, created
       end
     end
-    include Enumerable
-
-    private
-
-    def is_from_line? l
-      l =~ RE_F or return
-      addr, time = $'.split nil, 2
-      DateTime.parse time
-      addr =~ /@/
-    rescue ArgumentError, TypeError
-    end
 
   end
 
@@ -237,7 +232,7 @@ module Hermeneutics
       # :call-seq:
       #   Maildir.check( path)     -> true or false
       #
-      # Check whether path is a <code>Maildir</code>.
+      # Check whether path is a +Maildir+.
       #
       def check mailbox
         if File.directory? mailbox then
@@ -254,7 +249,7 @@ module Hermeneutics
     # :call-seq:
     #   maildir.create     -> self
     #
-    # Create the <code>Maildir</code>.
+    # Create the +Maildir+.
     #
     def create
       Dir.mkdir! @mailbox
@@ -266,53 +261,73 @@ module Hermeneutics
     end
 
     # :call-seq:
-    #   maildir.deliver( msg)     -> nil
+    #   maildir.store_raw( text, from, created)     -> nil
     #
-    # Store the mail into the local <code>Maildir</code>.
+    # Store some text that appears like a mail to the local +MBox+.
     #
-    def deliver msg
-      tmp = mkfilename TMP
-      File.open tmp, "w" do |f|
-        f.write msg
-      end
-      new = mkfilename NEW
-      File.rename tmp, new
-      new
+    def store_raw text, from, created
+      filename = mkfilename from, created
+      tpath = File.join @mailbox, TMP, filename
+      File.open tpath, File::CREAT|File::EXCL|File::WRONLY do |f| f.puts text end
+      cpath = File.join @mailbox, NEW, filename
+      File.link tpath, cpath
+      filename
+    rescue Errno::EEXIST
+      File.unlink tpath rescue nil
+      retry
+    ensure
+      File.unlink tpath
+    end
+
+    # :call-seq:
+    #   mbox.each_file { |filename| ... }    -> nil
+    #
+    # Iterate through +Maildir+.
+    #
+    def each_file new = nil
+      p = File.join @mailbox, new ? NEW : CUR
+      (Dir.new p).sort.each { |fn|
+        next if fn.starts_with? "."
+        path = File.join p, fn
+        yield path
+      }
     end
 
     # :call-seq:
     #   mbox.each { |mail| ... }    -> nil
     #
-    # Iterate through <code>MBox</code>.
+    # Iterate through +Maildir+.
     #
-    def each
-      p = File.join @mailbox, CUR
-      d = Dir.new p
-      d.each { |f|
-        next if f.starts_with? "."
-        File.open f, encoding: Encoding::ASCII_8BIT do |f|
-          yield f
+    def each_mail new = nil
+      lfrom = local_from
+      each_file new do |fn|
+        created = Time.at fn[ /\A(\d+)/, 1].to_i + fn[ /M(\d+)/, 1].to_i*0.000001
+        File.open fn, encoding: Encoding::ASCII_8BIT do |f|
+          from_host = fn[ /\.([.a-z0-9_+-]+)/, 1]
+          text = f.read
+          from = text[ /[a-z0-9.+-]+@#{Regexp.quote from_host}/]
+          yield text, from||lfrom, created
         end
-      }
+      end
     end
-    include Enumerable
 
     private
 
-    autoload :Socket, "socket"
-
-    def mkfilename d
-      dir = File.join @mailbox, d
-      c = 0
-      begin
-        n = "%.4f.%d_%d.%s" % [ Time.now.to_f, $$, c, Socket.gethostname]
-        path = File.join dir, n
-        File.open path, File::CREAT|File::EXCL do |f| end
-        path
-      rescue Errno::EEXIST
-        c += 1
-        retry
+    @seq = 0
+    class <<self
+      def seq! ; @seq += 1 ; end
+    end
+
+    def mkfilename from, created
+      host = if from =~ /@/ then
+        $'
+      else
+        require "socket"
+        Socket.gethostname
       end
+      created ||= Time.now
+      created = created.to_time
+      "#{created.to_i}M#{created.usec}P#$$Q#{self.class.seq!}.#{host}"
     end
 
   end