imap_processor 1.3 → 1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7ebadbaa317cabbc2b15ca821a55739a5689c614
+  data.tar.gz: 3fb713f7d17b9b04dd1d5f081725734fa90fad97
+SHA512:
+  metadata.gz: 027324815a2b2a44928ba687d74c23f06a66eef0470cdbfab5f5fe604b84a0b2b7b12ffd2cbc40202b4dd76a55083b8b42eb2806d0bb886980638015c63ee235
+  data.tar.gz: ee70746ac80bcac8339abcfb7281bdb6464a6eb6d384aeabff4873e96f460f41b18c9ef1475e371613c016edf8bb068f47ff52bb817405270c31e46527c4a995

data/History.rdoc

@@ -0,0 +1,83 @@
+=== 1.5 / 2014-08-06
+
+* 3 major enhancements:
+
+  * IMAPProcessor#process_args now returns an array of option hashes.
+  * IMAPProcessor.run now enumerates the array returned from process_args.
+  * You can now specify multiple host configs w/ an array of hashes in your config files.
+
+* 4 minor enhancements:
+
+  * Added --merge to imap_archive.
+  * Added --noop/-n to manually disable destructive actions. (needs to propagate down).
+  * Added imap_cleanse, imap_flag, imap_learn; migrated from IMAPCleanse.
+  * Added support for LOGIN. (bleything)
+
+* 7 bug fixes:
+
+  * Fixed initializers in flag and cleanse.
+  * Fixed odd bug w/ running on empty folders. Never saw that before. odd...
+  * Handle unparsable date entries. Stupid spammers...
+  * Now calculating latest month when not splitting directly from the date
+  * Removed 1.9/2.0 warnings.
+  * Removed dead rubyforge setting in Rakefile
+  * Split was still defaulting to true.
+
+=== 1.4 / 2011-01-10
+
+* 6 minor enhancements:
+
+  * Added explicit help option (-h didn't work)
+  * Added folder separator support (osx server uses '.' not '/')
+  * Added imap_mkdir command
+  * Added opts_file_name class var so subclass option processing can refer to file
+  * Extended imap_archive to archive multiple months per box, as necessary. Allowing easy archiving of big mailboxes
+  * Handles server-provided CAPABILITY to avoid an extra round-trip
+
+* 1 bug fix:
+
+  * Fixed doco.
+
+=== 1.3 / 2009-08-04
+
+* 1 major enhancement
+  * IMAP IDLE support now matches ruby trunk's support.  See Net::IMAP#idle
+    and Net::IMAP#idle_done
+
+=== 1.2 / 2009-06-02
+
+* 2 major enhancements
+  * imap_archive which archives old mail to dated mailboxes
+  * imap_idle which lists messages that were added or expunged from a mailbox
+
+* 4 minor enhancements
+  * Added IMAPProcessor#create_mailbox
+  * Added IMAPProcessor#delete_messages
+  * Added IMAPProcessor#move_messages
+  * Disabled verification of SSL certs for 1.9
+
+* 1 bug fix
+  * Fixed options file names, they should be Symbol keys
+
+=== 1.1.1 / 2009-05-19
+
+* 1 bug fix
+  * Got the skip test backwards
+
+=== 1.1 / 2009-05-18
+
+* 1 minor enhancement
+  * IMAPProcessor#each_message allows messages to be omitted from the returned
+    uid list (skipped)
+
+=== 1.0.1 / 2009-05-15
+
+* 2 bug fix
+  * Show correct name of options file for --password help
+  * Fix --quiet
+
+=== 1.0.0 / 2009-05-12
+
+* 1 major enhancement
+  * Birthday!
+

data/Manifest.txt

@@ -1,15 +1,24 @@
 .autotest
-History.txt
+History.rdoc
 Manifest.txt
-README.txt
+README.rdoc
 Rakefile
 bin/imap_archive
+bin/imap_cleanse
+bin/imap_flag
 bin/imap_idle
 bin/imap_keywords
+bin/imap_learn
+bin/imap_mkdir
 lib/imap_processor.rb
 lib/imap_processor/archive.rb
+lib/imap_processor/cleanse.rb
+lib/imap_processor/client.rb
+lib/imap_processor/flag.rb
 lib/imap_processor/idle.rb
 lib/imap_processor/keywords.rb
+lib/imap_processor/learn.rb
+lib/imap_processor/mkdir.rb
 lib/imap_sasl_plain.rb
 lib/net/imap/date.rb
 lib/net/imap/idle.rb

data/{README.txt → README.rdoc}

@@ -8,10 +8,17 @@ IMAPProcessor is a client for processing messages on an IMAP server.  It
 provides some basic mechanisms for connecting to an IMAP server, determining
 capabilities and handling messages.
 
-IMAPProcessor ships with the executables imap_keywords which can query an IMAP
-server for keywords set on messages in mailboxes, imap_idle which can show new
-messages in a mailbox and imap_archive which will archive old messages to a
-new mailbox.
+
+IMAPProcessor ships with several executables which can query and
+manipulate IMAP mailboxes in several different ways:
+
+imap_archive  :: Archives old messages to a new dated mailbox.
+imap_cleanse  :: Delete messages older than a certain age in specified mailboxes.
+imap_flag     :: Flag messages to/from certain people.
+imap_idle     :: Shows new messages in a mailbox.
+imap_keywords :: Queries an IMAP server for keywords set on messages
+imap_learn    :: Flags messages based on what you've flagged before.
+imap_mkdir    :: Ensures that certain mailboxes exist.
 
 == FEATURES/PROBLEMS:
 
@@ -21,7 +28,7 @@ new mailbox.
 
 == SYNOPSIS:
 
-See IMAPProcessor and IMAPProcessor::Keywords for details
+Run any command with --help for details.
 
 == REQUIREMENTS:
 
@@ -35,7 +42,7 @@ See IMAPProcessor and IMAPProcessor::Keywords for details
 
 (The MIT License)
 
-Copyright (c) 2009 Eric Hodel
+Copyright (c) Eric Hodel, Ryan Davis, Seattle.rb
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -4,10 +4,13 @@ require 'rubygems'
 require 'hoe'
 
 Hoe.plugin :seattlerb
+Hoe.plugin :rdoc
 
-Hoe.spec 'imap_processor' do |ip|
-  ip.rubyforge_name = 'seattlerb'
-  ip.developer 'Eric Hodel', 'drbrain@segment7.net'
+Hoe.spec 'imap_processor' do
+  developer 'Eric Hodel', 'drbrain@segment7.net'
+  developer 'Ryan Davis', 'ryand-ruby@zenspider.com'
+
+  license "MIT"
 end
 
 # vim: syntax=Ruby

data/bin/imap_cleanse

@@ -0,0 +1,5 @@
+#!/usr/local/bin/ruby -w
+
+require 'imap_processor/cleanse'
+
+IMAPProcessor::Cleanse.run ARGV

data/bin/imap_flag

@@ -0,0 +1,5 @@
+#!/usr/local/bin/ruby -w
+
+require 'imap_processor/flag'
+
+IMAPProcessor::Flag.run

data/bin/imap_learn

@@ -0,0 +1,5 @@
+#!/usr/local/bin/ruby -w
+
+require 'imap_processor/learn'
+
+IMAPProcessor::Learn.run

data/bin/imap_mkdir

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'imap_processor/mkdir'
+
+IMAPProcessor::Mkdir.run ARGV

data/lib/imap_processor.rb

@@ -15,13 +15,18 @@ require 'yaml'
 # * An initialize method that connects to an IMAP server and sets the @imap
 #   instance variable
 # * A run method that uses the IMAP connection to process messages.
+#
+# Reference:
+#
+#     email: http://www.ietf.org/rfc/rfc0822.txt
+#      imap: http://www.ietf.org/rfc/rfc3501.txt
 
 class IMAPProcessor
 
   ##
   # The version of IMAPProcessor you are using
 
-  VERSION = '1.3'
+  VERSION = "1.5"
 
   ##
   # Base IMAPProcessor error class
@@ -92,15 +97,16 @@ class IMAPProcessor
   #       required_options = {
   #         :MoveTo => [nil, "MoveTo not set"],
   #       }
-  #   
-  #     super __FILE__, args, required_options do |opts, options|
-  #       opts.banner << "Explain my_processor's executable"
-  #   
-  #       opts.on(      "--move=MAILBOX",
-  #               "Mailbox to move message to",
-  #               "Default: #{options[:MoveTo].inspect}",
-  #               "Options file name: :MoveTo") do |mailbox|
-  #         options[:MoveTo] = mailbox
+  #
+  #       super __FILE__, args, required_options do |opts, options|
+  #         opts.banner << "Explain my_processor's executable"
+  #
+  #         opts.on(      "--move=MAILBOX",
+  #                 "Mailbox to move message to",
+  #                 "Default: #{options[:MoveTo].inspect}",
+  #                 "Options file name: :MoveTo") do |mailbox|
+  #           options[:MoveTo] = mailbox
+  #         end
   #       end
   #     end
   #   end
@@ -109,10 +115,10 @@ class IMAPProcessor
 
   def self.process_args(processor_file, args,
                         required_options = {}) # :yield: OptionParser
-    opts_file_name = File.basename processor_file, '.rb'
-    opts_file_name = "imap_#{opts_file_name}" unless opts_file_name =~ /^imap_/
-    opts_file = File.expand_path "~/.#{opts_file_name}"
-    options = @@options.dup
+    @@opts_file_name = File.basename processor_file, '.rb'
+    @@opts_file_name = "imap_#{@@opts_file_name}" unless
+      @@opts_file_name =~ /^imap_/
+    opts_file = File.expand_path "~/.#{@@opts_file_name}"
 
     if required_options then
       required_options.each do |option, (default, message)|
@@ -122,6 +128,8 @@ class IMAPProcessor
       end
     end
 
+    defaults = [{}]
+
     if File.exist? opts_file then
       unless File.stat(opts_file).mode & 077 == 0 then
         $stderr.puts "WARNING! #{opts_file} is group/other readable or writable!"
@@ -129,165 +137,187 @@ class IMAPProcessor
         exit 1
       end
 
-      options.merge! YAML.load_file(opts_file)
+      defaults = YAML.load_file(opts_file)
+      defaults = [defaults] unless Array === defaults
     end
 
-    options[:SSL]        = true unless options.key? :SSL
-    options[:Username] ||= ENV['USER']
-    options[:Root]     ||= nil
-    options[:Verbose]  ||= false
-    options[:Debug]    ||= false
+    defaults.map { |default|
+      options = default.merge @@options.dup
 
-    required_options.each do |k,(v,m)|
-      options[k]       ||= v
-    end
+      options[:SSL]        = true unless options.key? :SSL
+      options[:Username] ||= ENV['USER']
+      options[:Root]     ||= nil
+      options[:Verbose]  ||= false
+      options[:Debug]    ||= false
 
-    op = OptionParser.new do |opts|
-      opts.program_name = File.basename $0
-      opts.banner = "Usage: #{opts.program_name} [options]\n\n"
+      required_options.each do |k,(v,_)|
+        options[k]       ||= v
+      end
 
-      opts.separator ''
-      opts.separator 'Connection options:'
+      op = OptionParser.new do |opts|
+        opts.program_name = File.basename $0
+        opts.banner = "Usage: #{opts.program_name} [options]\n\n"
 
-      opts.on("-H", "--host HOST",
-              "IMAP server host",
-              "Default: #{options[:Host].inspect}",
-              "Options file name: :Host") do |host|
-        options[:Host] = host
-      end
+        opts.separator ''
+        opts.separator 'Connection options:'
 
-      opts.on("-P", "--port PORT",
-              "IMAP server port",
-              "Default: The correct port SSL/non-SSL mode",
-              "Options file name: :Port") do |port|
-        options[:Port] = port
-      end
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
 
-      opts.on("-s", "--[no-]ssl",
-              "Use SSL for IMAP connection",
-              "Default: #{options[:SSL].inspect}",
-              "Options file name: :SSL") do |ssl|
-        options[:SSL] = ssl
-      end
+        opts.on("-H", "--host HOST",
+                "IMAP server host",
+                "Default: #{options[:Host].inspect}",
+                "Options file name: :Host") do |host|
+          options[:Host] = host
+        end
 
-      opts.on(      "--[no-]debug",
-              "Display Net::IMAP debugging info",
-              "Default: #{options[:Debug].inspect}",
-              "Options file name: :Debug") do |debug|
-        options[:Debug] = debug
-      end
+        opts.on("-P", "--port PORT",
+                "IMAP server port",
+                "Default: The correct port SSL/non-SSL mode",
+                "Options file name: :Port") do |port|
+          options[:Port] = port
+        end
 
-      opts.separator ''
-      opts.separator 'Login options:'
+        opts.on("-s", "--[no-]ssl",
+                "Use SSL for IMAP connection",
+                "Default: #{options[:SSL].inspect}",
+                "Options file name: :SSL") do |ssl|
+          options[:SSL] = ssl
+        end
 
-      opts.on("-u", "--username USERNAME",
-              "IMAP username",
-              "Default: #{options[:Username].inspect}",
-              "Options file name: :Username") do |username|
-        options[:Username] = username
-      end
+        opts.on(      "--[no-]debug",
+                "Display Net::IMAP debugging info",
+                "Default: #{options[:Debug].inspect}",
+                "Options file name: :Debug") do |debug|
+          options[:Debug] = debug
+        end
 
-      opts.on("-p", "--password PASSWORD",
-              "IMAP password",
-              "Default: Read from ~/.#{opts_file_name}",
-              "Options file name: :Password") do |password|
-        options[:Password] = password
-      end
+        opts.separator ''
+        opts.separator 'Login options:'
 
-      authenticators = Net::IMAP.send :class_variable_get, :@@authenticators
-      auth_types = authenticators.keys.sort.join ', '
-      opts.on("-a", "--auth AUTH", auth_types,
-              "IMAP authentication type override",
-              "Authentication type will be auto-",
-              "discovered",
-              "Default: #{options[:Auth].inspect}",
-              "Options file name: :Auth") do |auth|
-        options[:Auth] = auth
-      end
+        opts.on("-u", "--username USERNAME",
+                "IMAP username",
+                "Default: #{options[:Username].inspect}",
+                "Options file name: :Username") do |username|
+          options[:Username] = username
+        end
 
-      opts.separator ''
-      opts.separator "IMAP options:"
+        opts.on("-p", "--password PASSWORD",
+                "IMAP password",
+                "Default: Read from ~/.#{@@opts_file_name}",
+                "Options file name: :Password") do |password|
+          options[:Password] = password
+        end
 
-      opts.on("-r", "--root ROOT",
-              "Root of mailbox hierarchy",
-              "Default: #{options[:Root].inspect}",
-              "Options file name: :Root") do |root|
-        options[:Root] = root
-      end
+        authenticators = Net::IMAP.send :class_variable_get, :@@authenticators
+        auth_types = authenticators.keys.sort.join ', '
+        opts.on("-a", "--auth AUTH", auth_types,
+                "IMAP authentication type override",
+                "Authentication type will be auto-",
+                "discovered",
+                "Default: #{options[:Auth].inspect}",
+                "Options file name: :Auth") do |auth|
+          options[:Auth] = auth
+        end
 
-      opts.on("-b", "--boxes BOXES", Array,
-              "Comma-separated list of mailbox names",
-              "to search",
-              "Default: #{options[:Boxes].inspect}",
-              "Options file name: :Boxes") do |boxes|
-        options[:Boxes] = boxes
-      end
+        opts.separator ''
+        opts.separator "IMAP options:"
 
-      opts.on("-v", "--[no-]verbose",
-              "Be verbose",
-              "Default: #{options[:Verbose].inspect}",
-              "Options file name: :Verbose") do |verbose|
-        options[:Verbose] = verbose
-      end
+        opts.on("-r", "--root ROOT",
+                "Root of mailbox hierarchy",
+                "Default: #{options[:Root].inspect}",
+                "Options file name: :Root") do |root|
+          options[:Root] = root
+        end
 
-      opts.on("-q", "--quiet",
-              "Be quiet") do
-        options[:Verbose] = false
-      end
+        opts.on("-b", "--boxes BOXES", Array,
+                "Comma-separated list of mailbox names",
+                "to search",
+                "Default: #{options[:Boxes].inspect}",
+                "Options file name: :Boxes") do |boxes|
+          options[:Boxes] = boxes
+        end
 
-      if block_given? then
-        opts.separator ''
-        opts.separator "#{self} options:"
+        opts.on("-v", "--[no-]verbose",
+                "Be verbose",
+                "Default: #{options[:Verbose].inspect}",
+                "Options file name: :Verbose") do |verbose|
+          options[:Verbose] = verbose
+        end
 
-        yield opts, options if block_given?
-      end
+        opts.on("-n", "--noop",
+                "Perform no destructive operations",
+                "Best used with the verbose option",
+                "Default: #{options[:Noop].inspect}",
+                "Options file name: Noop") do |noop|
+          options[:Noop] = noop
+        end
 
-      @@extra_options.each do |block|
-        block.call opts, options
-      end
+        opts.on("-q", "--quiet",
+                "Be quiet") do
+          options[:Verbose] = false
+        end
+
+        if block_given? then
+          opts.separator ''
+          opts.separator "#{self} options:"
+
+          yield opts, options if block_given?
+        end
+
+        @@extra_options.each do |block|
+          block.call opts, options
+        end
 
-      opts.separator ''
+        opts.separator ''
 
-      opts.banner << <<-EOF
+        opts.banner << <<-EOF
 
-Options may also be set in the options file ~/.#{opts_file_name}
+Options may also be set in the options file ~/.#{@@opts_file_name}
 
-Example ~/.#{opts_file_name}:
+Example ~/.#{@@opts_file_name}:
 \tHost=mail.example.com
 \tPassword=my password
 
-      EOF
-    end
+        EOF
+
+      end # OptionParser.new do
 
-    op.parse! args
-
-    options[:Port] ||= options[:SSL] ? 993 : 143
-
-    if options[:Host].nil? or
-       options[:Password].nil? or
-       options[:Boxes].nil? or
-       required_options.any? { |k,(v,m)| options[k].nil? } then
-      $stderr.puts op
-      $stderr.puts
-      $stderr.puts "Host name not set" if options[:Host].nil?
-      $stderr.puts "Password not set"  if options[:Password].nil?
-      $stderr.puts "Boxes not set"     if options[:Boxes].nil?
-      required_options.each do |option_name, (option_value, missing_message)|
-        $stderr.puts missing_message if options[option_name].nil?
+      op.parse! args
+
+      options[:Port] ||= options[:SSL] ? 993 : 143
+
+      # HACK: removed :Boxes -- push down
+      required_keys = [:Host, :Password] + required_options.keys
+      if required_keys.any? { |k| options[k].nil? } then
+        $stderr.puts op
+        $stderr.puts
+        $stderr.puts "Host name not set" if options[:Host].nil?
+        $stderr.puts "Password not set"  if options[:Password].nil?
+        $stderr.puts "Boxes not set"     if options[:Boxes].nil?
+        required_options.each do |option_name, (_, missing_message)|
+          $stderr.puts missing_message if options[option_name].nil?
+        end
+        exit 1
       end
-      exit 1
-    end
 
-    return options
+      options
+    } # defaults.map
   end
 
   ##
   # Sets up an IMAP processor's options then calls its \#run method.
 
   def self.run(args = ARGV, &block)
-    options = process_args args
-    client = new(options, &block)
-    client.run
+    client = nil
+    multi_options = process_args args
+
+    multi_options.each do |options|
+      client = new(options, &block)
+      client.run
+    end
   rescue Interrupt
     exit
   rescue SystemExit
@@ -312,10 +342,27 @@ Example ~/.#{opts_file_name}:
     Net::IMAP.debug = options[:Debug]
   end
 
+  ##
+  # Extracts capability information for +imap+ from +res+ or by contacting the
+  # server.
+
+  def capability imap, res = nil
+    return imap.capability unless res
+
+    data = res.data
+
+    if data.code and data.code.name == 'CAPABILITY' then
+      data.code.data.split ' '
+    else
+      imap.capability
+    end
+  end
+
   ##
   # Connects to IMAP server +host+ at +port+ using ssl if +ssl+ is true then
-  # logs in as +username+ with +password+.  IMAPProcessor is only known to
-  # work with PLAIN auth on SSL sockets.
+  # authenticates with +username+ and +password+.  IMAPProcessor is only known
+  # to work with PLAIN auth on SSL sockets.  IMAPProcessor does not support
+  # LOGIN.
   #
   # Returns a Connection object.
 
@@ -328,23 +375,35 @@ Example ~/.#{opts_file_name}:
     imap = Net::IMAP.new host, port, ssl, nil, false
     log "Connected to imap://#{host}:#{port}/"
 
-    capability = imap.capability
+    capabilities = capability imap, imap.greeting
 
-    log "Capabilities: #{capability.join ', '}"
+    log "Capabilities: #{capabilities.join ', '}"
 
-    auth_caps = capability.select { |c| c =~ /^AUTH/ }
+    auth_caps = capabilities.select { |c| c =~ /^AUTH/ }
 
     if auth.nil? then
       raise "Couldn't find a supported auth type" if auth_caps.empty?
       auth = auth_caps.first.sub(/AUTH=/, '')
     end
 
-    auth = auth.upcase
-    log "Trying #{auth} authentication"
-    imap.authenticate auth, username, password
-    log "Logged in as #{username}"
+    # Net::IMAP supports using AUTHENTICATE with LOGIN, PLAIN, and
+    # CRAM-MD5... if the server reports a different AUTH method, then we
+    # should fall back to using LOGIN
+    if %w( LOGIN PLAIN CRAM-MD5 ).include?( auth.upcase )
+      auth = auth.upcase
+      log "Trying #{auth} authentication"
+      res = imap.authenticate auth, username, password
+      log "Logged in as #{username} using AUTHENTICATE"
+    else
+      log "Trying to authenticate via LOGIN"
+      res = imap.login username, password
+      log "Logged in as #{username} using LOGIN"
+    end
+
+    # CAPABILITY may have changed
+    capabilities = capability imap, res
 
-    connection = Connection.new imap, capability
+    connection = Connection.new imap, capabilities
 
     if block_given? then
       begin
@@ -399,8 +458,6 @@ Example ~/.#{opts_file_name}:
     uids = []
 
     each_part parts, true do |uid, message|
-      skip = false
-
       mail = TMail::Mail.parse message
 
       begin
@@ -498,7 +555,7 @@ Example ~/.#{opts_file_name}:
 
     begin
       imap.copy uids, destination
-    rescue Net::IMAP::NoResponseError => e
+    rescue Net::IMAP::NoResponseError
       # ruby-lang bug #1713
       #raise unless e.response.data.code.name == 'TRYCREATE'
       create_mailbox destination
@@ -531,4 +588,3 @@ Example ~/.#{opts_file_name}:
   end
 
 end
-