imap_guard 0.0.3 → 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d95cc42f451c9e8d2230c9ed670c5b5cb5f42d20
+  data.tar.gz: 22a08ac744d604430aa795cf156f8b0ea899a9fc
+SHA512:
+  metadata.gz: 9a7fe8edceec8be75626f91f69b8228bd1e2f4205d4fe52f742cf5bea0b828f79851e3ce9b843c1941eaefe63092541204c61f8c225bcbdcf54dfc3e7d29c1b7
+  data.tar.gz: 47a6ba91f840a30ad8164a84593f3fdbd91fdf5c46bd798a74f1af8926152b66e0c2af02ddfcebfc3f2166fe04dd6f843fe04cf6213266daba6822f4e79e7fc2

data/.ruby-version

@@ -1 +1 @@
-1.9.3
+2.1.0

data/.travis.yml

@@ -5,12 +5,13 @@ after_script:
 rvm:
   - 1.9.3
   - 2.0.0
+  - 2.1.0
   - ruby-head
-  - rbx-19mode
+  - rbx
 matrix:
   allow_failures:
     - rvm: ruby-head
-    - rvm: rbx-19mode
+    - rvm: rbx
 notifications:
   email:
     on_success: always

data/README.md

@@ -1,6 +1,13 @@
 # ImapGuard [![Build Status](https://secure.travis-ci.org/infertux/imap_guard.png?branch=master)](https://travis-ci.org/infertux/imap_guard) [![Dependency Status](https://gemnasium.com/infertux/imap_guard.png)](https://gemnasium.com/infertux/imap_guard) [![Code Climate](https://codeclimate.com/github/infertux/imap_guard.png)](https://codeclimate.com/github/infertux/imap_guard)
 
-A guard for your IMAP mailboxes.
+**A guard for your IMAP mailboxes.**
+
+  * [Source Code](https://github.com/infertux/imap_guard "Source Code on Github")
+  * [Bug Tracker](https://github.com/infertux/imap_guard/issues "Bug Tracker on Github")
+  * [API documentation](http://rubydoc.info/gems/imap_guard/frames "API Documentation on Rubydoc")
+  * [Rubygem](https://rubygems.org/gems/imap_guard "ImapGuard on Rubygems")
+  * [Continuous Integration](https://travis-ci.org/infertux/imap_guard "ImapGuard on Travis-CI")
+  * [Dependencies](https://gemnasium.com/infertux/imap_guard "ImapGuard dependencies on Gemnasium")
 
 ImapGuard connects to your IMAP server and processes your emails.
 You can finely pick them thanks to advanced search queries and Ruby blocks.
@@ -16,6 +23,9 @@ It can be used by a disposable script to clean things up or with a cron job to k
 
 ## Usage
 
+Read below for detailed explanations.
+If you prefer a quick overview, you can take a look at [this example](https://github.com/infertux/imap_guard/blob/master/examples/example.rb).
+
 Example initialization:
 
 ```ruby
@@ -29,16 +39,16 @@ SETTINGS = {
   read_only: true # don't perform any modification aka dry-run mode
 }
 
-guard = IMAPGuard::Guard.new SETTINGS
+guard = ImapGuard::Guard.new SETTINGS
 guard.login # authenticate the user
 guard.select 'INBOX.ops' # select the mailbox
 ```
 
 IMAP search query syntax can be a bit tricky.
-`IMAPGuard::Query` can help you to build queries with a simple Ruby DSL:
+`ImapGuard::Query` can help you to build queries with a simple Ruby DSL:
 
 ```ruby
-base_query = IMAPGuard::Query.new.unflagged.unanswered.seen.freeze
+base_query = ImapGuard::Query.new.unflagged.unanswered.seen.freeze
 query = base_query.dup.before(7).subject("abc").from("root")
 p query #=> ["UNFLAGGED", "UNANSWERED", "SEEN", "BEFORE", "13-Mar-2013", "SUBJECT", "abc", "FROM", "root"]
 guard.delete query # will delete every emails which match this query

data/examples/example.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+
+require 'imap_guard'
+
+SETTINGS = {
+  host: 'imap.googlemail.com',
+  port: 993,
+  username: 'you@gmail.com',
+  password: 'your_pass',
+}
+
+settings = SETTINGS.merge({ read_only: false })
+base_query = ImapGuard::Query.new.unflagged.unanswered.freeze
+guard = ImapGuard::Guard.new settings
+# guard.debug = ->(mail) { print "#{mail.subject}: " }
+guard.login
+
+guard.select 'INBOX'
+
+# Github
+%w(github.com notifications@travis-ci.org app@gemnasium.com).map do |from|
+  base_query.dup.from(from)
+end.each do |query|
+  guard.move query, 'INBOX.Github'
+end
+
+# To Do
+guard.move base_query.dup.from("me").to("me"), 'INBOX.TODO'
+
+# Ops
+guard.select 'INBOX.Ops'
+query = base_query.dup.seen
+guard.delete query.dup.subject("monit alert -- ").before(7)
+guard.delete query.dup.subject("CRON-APT completed on ").before(3)
+guard.delete query.dup.subject("Logwatch for ").before(7)
+guard.select 'INBOX'
+
+# Uni
+guard.move base_query.dup.or.from("uni.tld").to("uni.tld"), 'INBOX.Uni'
+
+# Bye!
+guard.disconnect
+

data/imap_guard.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency 'mail', '~> 2.5.3'
-  spec.add_dependency 'colored', '~> 1.2'
+  spec.add_dependency 'term-ansicolor', '~> 1.2.2'
 
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'rake'
@@ -29,4 +29,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rb-inotify'
   spec.add_development_dependency 'cane'
   spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'redcarpet' # for yardoc
 end

data/lib/imap_guard/guard.rb

@@ -1,18 +1,27 @@
 require 'net/imap'
 require 'ostruct'
 require 'mail'
-require 'colored'
+require 'term/ansicolor'
+String.send(:include, Term::ANSIColor)
+Term::ANSIColor::coloring = STDOUT.isatty
 
-module IMAPGuard
+module ImapGuard
   # Guard allows you to process your mailboxes.
   class Guard
-    # [Proc] Matched emails are passed to this debug lambda if present
+    # List of required settings
+    REQUIRED_SETTINGS = [:host, :port, :username, :password]
+
+    # List of optional settings
+    OPTIONAL_SETTINGS = [:read_only, :verbose]
+
+    # @return [Proc, nil] Matched emails are passed to this debug lambda if present
     attr_accessor :debug
 
-    # @return [OpenStruct] IMAPGuard settings
+    # @note The settings are frozen
+    # @return [OpenStruct] ImapGuard settings
     attr_reader :settings
 
-    # @return [String] Currently selected mailbox
+    # @return [String, nil] Currently selected mailbox
     attr_reader :mailbox
 
     def initialize settings
@@ -29,7 +38,6 @@ module IMAPGuard
     end
 
     # Selects a mailbox (folder)
-    # @see {settings.read_only}
     # @return [void]
     def select mailbox
       if @settings.read_only
@@ -72,7 +80,7 @@ module IMAPGuard
       process query, operation, &filter
     end
 
-    # @return [Array] Sorted list of all mailboxes
+    # @return [Array<String>] Sorted list of all mailboxes
     def list
       @imap.list("", "*").map(&:name).sort
     end
@@ -138,7 +146,7 @@ module IMAPGuard
 
     def search query
       unless [Array, String].any? { |type| query.is_a? type }
-        raise TypeError, "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
@@ -161,16 +169,14 @@ module IMAPGuard
     end
 
     def settings= settings
-      required = %w(host port username password).map!(&:to_sym)
-      missing = required - settings.keys
+      missing = REQUIRED_SETTINGS - settings.keys
       raise ArgumentError, "Missing settings: #{missing}" unless missing.empty?
 
-      optional = %w(read_only verbose).map!(&:to_sym)
-      unknown = settings.keys - required - optional
+      unknown = settings.keys - REQUIRED_SETTINGS - OPTIONAL_SETTINGS
       raise ArgumentError, "Unknown settings: #{unknown}" unless unknown.empty?
 
       @settings = OpenStruct.new(settings).freeze
-      puts "DRY-RUN MODE ENABLED".yellow.bold.reversed if @settings.read_only
+      puts "DRY-RUN MODE ENABLED".yellow.bold.negative if @settings.read_only
     end
   end
 end

data/lib/imap_guard/query.rb

@@ -1,49 +1,82 @@
-module IMAPGuard
+module ImapGuard
   # Query is a neat DSL to help you generate IMAP search queries.
+  # @note All methods return self so they can be chained.
   class Query < Array
-    # Messages that have the \Seen flag set.
-    # @return [Query] self
+    # Messages that have the +\Seen+ flag set.
+    # @return [self]
     def seen
       self << 'SEEN'
     end
 
-    # Messages that do not have the \Answered flag set.
-    # @return [Query] self
+    # Messages that do not have the +\Answered+ flag set.
+    # @return [self]
     def unanswered
       self << 'UNANSWERED'
     end
 
-    # Messages that do not have the \Flagged flag set.
-    # @return [Query] self
+    # Messages that do not have the +\Flagged+ flag set.
+    # @return [self]
     def unflagged
       self << 'UNFLAGGED'
     end
 
+    # Messages with the +\Deleted+ flag set.
+    # @return [self]
+    def deleted
+      self << 'DELETED'
+    end
+
     # Messages that match either search key.
+    # @param search_key1 Optional search key to pass to +OR+
+    # @param search_key2 Optional search key to pass to +OR+
     # @note Reverse polish notation is expected,
     #   i.e. OR <search-key1> <search-key2>
-    # @return [Query] self
-    def or
+    # @example
+    #   or.unanswered.unflagged     #=> ["OR", "UNANSWERED", "UNFLAGGED"]
+    #   or(:unanswered, :unflagged) #=> ["OR", "UNANSWERED", "UNFLAGGED"]
+    # @return [self]
+    def or search_key1 = nil, search_key2 = nil
       self << 'OR'
+
+      if search_key1 and search_key2
+        send(search_key1)
+        send(search_key2)
+      elsif search_key1 or search_key2
+        raise ArgumentError, "You must give either zero or two arguments."
+      end
+
+      self
+    end
+
+    # Messages that do not match the specified search key.
+    # @param search_key Optional search key to pass to +NOT+
+    # @example
+    #   not.deleted   #=> ["NOT", "DELETED"]
+    #   not(:deleted) #=> ["NOT", "DELETED"]
+    # @return [self]
+    def not search_key = nil
+      self << 'NOT'
+      send(search_key) if search_key
+      self
     end
 
     # Messages that contain the specified string in the envelope
     # structure's SUBJECT field.
-    # @return [Query] self
+    # @return [self]
     def subject string
       self << 'SUBJECT' << string
     end
 
     # Messages that contain the specified string in the envelope
     # structure's FROM field.
-    # @return [Query] self
+    # @return [self]
     def from string
       self << 'FROM' << string
     end
 
     # Messages that contain the specified string in the envelope
     # structure's TO field.
-    # @return [Query] self
+    # @return [self]
     def to string
       self << 'TO' << string
     end
@@ -51,10 +84,10 @@ module IMAPGuard
     # 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
+    #   - [String]: uses it as is
+    #   - [Fixnum]: _n_ days before today
+    #   - [Date]: uses this date
+    # @return [self]
     def before date
       case date
       when String
@@ -64,7 +97,7 @@ module IMAPGuard
       when Date
         date = date.strftime '%e-%b-%Y'
       else
-        raise ArgumentError, "#{date.inspect} is invalid"
+        raise ArgumentError, "#{date.inspect} is invalid."
       end
 
       self << 'BEFORE' << date

data/lib/imap_guard/version.rb

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

data/spec/imap_guard/guard_spec.rb

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-module IMAPGuard
+module ImapGuard
   describe Guard do
     before do
       $stdout = StringIO.new # mute stdout - comment to debug
@@ -216,9 +216,11 @@ module IMAPGuard
       it "freezes the settings" do
         guard = Guard.new(settings)
 
+        exception = (RUBY_VERSION >= "2.1.0" ? RuntimeError : TypeError)
+
         expect {
           guard.settings.host = 'example.net'
-        }.to raise_error(TypeError, /frozen/)
+        }.to raise_error(exception, /frozen/)
       end
 
       it "raises ArgumentError if any required key is missing" do

data/spec/imap_guard/query_spec.rb

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-module IMAPGuard
+module ImapGuard
   describe Query do
     describe "#initialize" do
       it { should be_empty }
@@ -27,10 +27,38 @@ module IMAPGuard
       end
     end
 
+    describe "#deleted" do
+      it "adds 'DELETED'" do
+        subject.deleted
+        subject.last.should eq 'DELETED'
+      end
+    end
+
     describe "#or" do
-      it "adds 'OR'" do
-        subject.or
-        subject.last.should eq 'OR'
+      context "without a search key" do
+        it "adds 'OR'" do
+          subject.or
+          subject.last.should eq 'OR'
+        end
+      end
+
+      context "with search keys" do
+        it "adds 'OR UNANSWERED UNFLAGGED '" do
+          subject.or(:unanswered, :unflagged)
+          subject.last(3).should eq ["OR", "UNANSWERED", "UNFLAGGED"]
+        end
+      end
+
+      context "with only one non-nil search key" do
+        it "raises ArgumentError" do
+          expect {
+            subject.or(:whatever)
+          }.to raise_error(ArgumentError)
+
+          expect {
+            subject.or(nil, :whatever)
+          }.to raise_error(ArgumentError)
+        end
       end
     end
 
@@ -55,6 +83,22 @@ module IMAPGuard
       end
     end
 
+    describe "#not" do
+      context "without a search key" do
+        it "adds 'NOT'" do
+          subject.not.deleted
+          subject.last(2).should eq ["NOT", "DELETED"]
+        end
+      end
+
+      context "with a search key" do
+        it "adds 'NOT DELETED'" do
+          subject.not(:deleted)
+          subject.last(2).should eq ["NOT", "DELETED"]
+        end
+      end
+    end
+
     describe "#before" do
       context "when I pass 'nil' as an argument" do
         it "raises" do

metadata

@@ -1,174 +1,167 @@
 --- !ruby/object:Gem::Specification
 name: imap_guard
 version: !ruby/object:Gem::Version
-  version: 0.0.3
-  prerelease: 
+  version: 0.0.4
 platform: ruby
 authors:
 - Cédric Félizard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-04 00:00:00.000000000 Z
+date: 2014-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mail
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 2.5.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 2.5.3
 - !ruby/object:Gem::Dependency
-  name: colored
+  name: term-ansicolor
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: 1.2.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: 1.2.2
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rb-inotify
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: cane
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: A guard for your IMAP server
@@ -178,15 +171,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .ruby-version
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
 - Gemfile
 - Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/example.rb
 - imap_guard.gemspec
 - lib/imap_guard.rb
 - lib/imap_guard/guard.rb
@@ -198,33 +192,26 @@ files:
 homepage: https://github.com/infertux/imap_guard
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 903698273
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 903698273
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.2.0
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: A guard for your IMAP server
 test_files:
 - spec/imap_guard/guard_spec.rb