imap_guard 0.0.2 → 0.0.3

data/README.md

@@ -49,7 +49,7 @@ For instance, the pattern passed to `subject` and `from` is a mere string.
 IMAP doesn't allow advanced filtering such as regexp matching.
 
 To do so, you can pass an optional block to `delete`.
-The yielded object is a [Mail](https://github.com/mikel/mail) instance of the current mail providing many methods.
+The yielded object is a [Mail] instance of the current mail providing many methods.
 However, wrapping the mail into a nice `Mail` object is slow and you should avoid to use it if you can.
 
 ```ruby
@@ -84,6 +84,36 @@ guard.move query, 'destination_folder' do |mail|
 end
 ```
 
+### Advanced features
+
+#### Mailbox list
+
+You can list all mailboxes:
+
+```ruby
+p guard.list
+```
+
+#### Selected mailbox
+
+You can output the currently selected mailbox:
+
+```ruby
+p guard.mailbox # nil if none has been selected
+```
+
+#### Debug block
+
+You can pass a block which will be yielded for each matched email:
+
+```ruby
+# Print out the subject for each email
+guard.debug = ->(mail) { print "#{mail.subject}: " }
+```
+
+You can think of it as Ruby's [Object#tap](http://ruby-doc.org/core-2.0/Object.html#method-i-tap) method.
+Note this is slow since it needs to fetch the whole email to return a [Mail] object.
+
 ## Contributing
 
 Bug reports and patches are most welcome.
@@ -92,3 +122,6 @@ Bug reports and patches are most welcome.
 
 MIT
 
+
+[Mail]: https://github.com/mikel/mail
+

data/lib/imap_guard/guard.rb

@@ -4,53 +4,98 @@ require 'mail'
 require 'colored'
 
 module IMAPGuard
+  # Guard allows you to process your mailboxes.
   class Guard
+    # [Proc] Matched emails are passed to this debug lambda if present
+    attr_accessor :debug
+
+    # @return [OpenStruct] IMAPGuard settings
     attr_reader :settings
 
+    # @return [String] Currently selected mailbox
+    attr_reader :mailbox
+
     def initialize settings
       self.settings = settings
     end
 
+    # Authenticates to the given IMAP server
     # @see http://www.ruby-doc.org/stdlib-1.9.3/libdoc/net/imap/rdoc/Net/IMAP.html#method-c-new
+    # @return [void]
     def login
       @imap = Net::IMAP.new(@settings.host, @settings.port, true, nil, false)
       @imap.login(@settings.username, @settings.password)
       verbose.puts "Logged in successfully"
     end
 
+    # Selects a mailbox (folder)
+    # @see {settings.read_only}
+    # @return [void]
     def select mailbox
       if @settings.read_only
         @imap.examine(mailbox) # open in read-only
       else
         @imap.select(mailbox) # open in read-write
       end
+      @mailbox = mailbox
     end
 
+    # Moves messages matching the query and filter block
+    # @param query IMAP query
     # @param mailbox Destination mailbox
+    # @param filter Optional filter block
+    # @return [void]
     def move query, mailbox, &filter
       operation = lambda { |message_id|
-        @imap.copy(message_id, mailbox) unless @settings.read_only
-        @imap.store(message_id, "+FLAGS", [:Deleted])
-        "moved to #{mailbox}".cyan
+        unless @settings.read_only
+          @imap.copy(message_id, mailbox)
+          @imap.store(message_id, "+FLAGS", [Net::IMAP::DELETED])
+        end
+
+        "moved to #{mailbox}".yellow
       }
       process query, operation, &filter
     end
 
+    # Deletes messages matching the query and filter block
+    # @param query IMAP query
+    # @param filter Optional filter block
+    # @return [void]
     def delete query, &filter
       operation = lambda { |message_id|
-        @imap.store(message_id, "+FLAGS", [:Deleted])
+        unless @settings.read_only
+          @imap.store(message_id, "+FLAGS", [Net::IMAP::DELETED])
+        end
+
         'deleted'.red
       }
       process query, operation, &filter
     end
 
+    # @return [Array] Sorted list of all mailboxes
+    def list
+      @imap.list("", "*").map(&:name).sort
+    end
+
+    # Sends a EXPUNGE command to permanently remove from the currently selected
+    # mailbox all messages that have the Deleted flag set.
+    # @return [void]
     def expunge
-      @imap.expunge
+      @imap.expunge unless @settings.read_only
     end
 
+    # Sends a CLOSE command to close the currently selected mailbox. The CLOSE
+    # command permanently removes from the mailbox all messages that have the
+    # Deleted flag set.
+    # @return [void]
     def close
-      puts "Expunging deleted messages and closing mailbox..."
-      @imap.close
+      @imap.close unless @settings.read_only
+    end
+
+    # Disconnects from the server.
+    # @return [void]
+    def disconnect
+      @imap.disconnect
     end
 
   private
@@ -60,35 +105,44 @@ module IMAPGuard
       count = message_ids.size
 
       message_ids.each_with_index do |message_id, index|
-        print "Processing UID #{message_id} (#{index + 1}/#{count}): "
+        print "Processing UID #{message_id} (#{index.succ}/#{count}): "
 
         result = true
-        if block_given?
+        if block_given? or debug
           mail = fetch_mail message_id
-          result = yield(mail)
-          verbose.print "(given filter result: #{result.inspect}) "
+
+          debug.call(mail) if debug
+
+          if block_given?
+            result = yield(mail)
+            verbose.print "(given filter result: #{result.inspect}) "
+          end
         end
 
         if result
           puts operation.call(message_id)
         else
-          puts "ignored".yellow
+          puts "ignored".green
         end
       end
+
+    ensure
+      expunge
     end
 
+    # @note We use "BODY.PEEK[]" to avoid setting the \Seen flag.
     def fetch_mail message_id
-      msg = @imap.fetch(message_id, 'RFC822')[0].attr['RFC822']
+      msg = @imap.fetch(message_id, 'BODY.PEEK[]').first.attr['BODY[]']
       Mail.read_from_string msg
     end
 
     def search query
       unless [Array, String].any? { |type| query.is_a? type }
-        raise ArgumentError, "query must be either a string holding the entire search string, or a single-dimension array of search keywords and arguments"
+        raise TypeError, "query must be either a string holding the entire search string, or a single-dimension array of search keywords and arguments"
       end
 
       messages = @imap.search query
-      puts "Query: #{query.inspect}: #{messages.count} results".cyan
+      puts "Query on #{mailbox}: #{query.inspect}: #{messages.count} results".cyan
 
       messages
     end
@@ -99,7 +153,7 @@ module IMAPGuard
       else
         # anonymous null object
         Class.new do
-          def method_missing(*args, &block)
+          def method_missing(*)
             nil
           end
         end.new

data/lib/imap_guard/query.rb

@@ -1,25 +1,60 @@
 module IMAPGuard
+  # Query is a neat DSL to help you generate IMAP search queries.
   class Query < Array
+    # Messages that have the \Seen flag set.
+    # @return [Query] self
     def seen
       self << 'SEEN'
     end
 
+    # Messages that do not have the \Answered flag set.
+    # @return [Query] self
     def unanswered
       self << 'UNANSWERED'
     end
 
+    # Messages that do not have the \Flagged flag set.
+    # @return [Query] self
     def unflagged
       self << 'UNFLAGGED'
     end
 
+    # Messages that match either search key.
+    # @note Reverse polish notation is expected,
+    #   i.e. OR <search-key1> <search-key2>
+    # @return [Query] self
+    def or
+      self << 'OR'
+    end
+
+    # Messages that contain the specified string in the envelope
+    # structure's SUBJECT field.
+    # @return [Query] self
     def subject string
       self << 'SUBJECT' << string
     end
 
+    # Messages that contain the specified string in the envelope
+    # structure's FROM field.
+    # @return [Query] self
     def from string
       self << 'FROM' << string
     end
 
+    # Messages that contain the specified string in the envelope
+    # structure's TO field.
+    # @return [Query] self
+    def to string
+      self << 'TO' << string
+    end
+
+    # Messages whose internal date (disregarding time and timezone)
+    # is earlier than the specified date.
+    # @param date Depending of its type:
+    #   - String: uses it as is
+    #   - Fixnum: _n_ days before today
+    #   - Date: uses this date
+    # @return [Query] self
     def before date
       case date
       when String

data/lib/imap_guard/version.rb

@@ -1,3 +1,4 @@
 module ImapGuard
-  VERSION = "0.0.2"
+  # [String] ImapGuard version
+  VERSION = "0.0.3"
 end

data/lib/imap_guard.rb

@@ -2,5 +2,6 @@ require "imap_guard/version"
 require "imap_guard/guard"
 require "imap_guard/query"
 
+# ImapGuard default module
 module ImapGuard
 end

data/spec/imap_guard/guard_spec.rb

@@ -6,6 +6,10 @@ module IMAPGuard
       $stdout = StringIO.new # mute stdout - comment to debug
     end
 
+    after do
+      $stdout = STDOUT
+    end
+
     let(:settings) do
       {
         host: 'localhost',
@@ -16,7 +20,7 @@ module IMAPGuard
     end
 
     let(:imap) {
-      double('Net::IMAP', search: [7, 28])
+      double('Net::IMAP', search: [7, 28], expunge: nil, select: nil, list: [])
     }
 
     def guard_instance custom_settings = {}
@@ -46,6 +50,26 @@ module IMAPGuard
       end
     end
 
+    describe "#mailbox" do
+      it "returns nil when no mailbox has been selected" do
+        guard_instance.mailbox.should be_nil
+      end
+
+      it "returns the currently selected mailbox" do
+        guard = guard_instance
+
+        guard.select 'Sent'
+        guard.mailbox.should eq 'Sent'
+      end
+    end
+
+    describe "#list" do
+      it "returns the list of mailboxes" do
+        imap.should_receive(:list)
+        guard_instance.list.should eq []
+      end
+    end
+
     describe "#search" do
       before do
         imap.should_receive(:search) do |arg|
@@ -88,6 +112,16 @@ module IMAPGuard
 
           guard.send(:process, 'ALL', opeartion)
         end
+
+        context "with a debug proc" do
+          it "calls the proc" do
+            block = ->(mail) {}
+            guard.debug = block
+            block.should_receive(:call).twice
+
+            guard.send(:process, 'ALL', opeartion)
+          end
+        end
       end
 
       context "with a filter block" do
@@ -151,6 +185,13 @@ module IMAPGuard
       end
     end
 
+    describe "#disconnect" do
+      it "disconnects from the server" do
+        imap.should_receive(:disconnect)
+        guard_instance.disconnect
+      end
+    end
+
     describe "#verbose" do
       context "with settings.verbose = true" do
         let(:guard) { guard_instance(verbose: true) }

data/spec/imap_guard/query_spec.rb

@@ -27,6 +27,13 @@ module IMAPGuard
       end
     end
 
+    describe "#or" do
+      it "adds 'OR'" do
+        subject.or
+        subject.last.should eq 'OR'
+      end
+    end
+
     describe "#subject" do
       it "adds the search value" do
         subject.subject("Hey you")
@@ -41,6 +48,13 @@ module IMAPGuard
       end
     end
 
+    describe "#to" do
+      it "adds the search value" do
+        subject.to("root@example.net")
+        subject.last.should eq "root@example.net"
+      end
+    end
+
     describe "#before" do
       context "when I pass 'nil' as an argument" do
         it "raises" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imap_guard
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-24 00:00:00.000000000 Z
+date: 2013-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mail
@@ -210,7 +210,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -500228931
+      hash: 903698273
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -219,7 +219,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -500228931
+      hash: 903698273
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25