gmail 0.4.0 → 0.4.2

data/Rakefile

@@ -1,45 +1,35 @@
-# -*- ruby -*-
-$:.unshift(File.expand_path('../lib', __FILE__))
-require 'gmail/version'
-require 'rspec/core/rake_task'
-require 'rake/rdoctask'
-
-RSpec::Core::RakeTask.new(:spec) do |t|
-  t.pattern = 'spec/**/*_spec.rb'
-  t.rspec_opts = %q[-c -b]
-end
-
-RSpec::Core::RakeTask.new(:rcov) do |t|
-  t.rcov = true
-  t.rspec_opts = %q[-c -b]
-  t.rcov_opts = %q[-T -x "spec"]
-end
-
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "Gmail #{Gmail.version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-task :default => :spec
-
-desc "Build current version as a rubygem"
-task :build do
-  `gem build gmail.gemspec`
-  `mkdir -p pkg`
-  `mv gmail-*.gem pkg/`
-end
-
-desc "Relase current version to rubygems.org"
-task :release => :build do
-  `git tag -am "Version bump to #{Gmail.version}" v#{Gmail.version}`
-  `git push origin master`
-  `git push origin master --tags`
-  `gem push pkg/gmail-#{Gmail.version}.gem`
-end
-
-desc "Perform installation via rubygems"
-task :install => :build do
-  `gem install pkg/gmail-#{Gmail.version}.gem`
-end
+#!/usr/bin/env rake
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Gmail for Ruby #{Gmail::VERSION}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  task :spec do
+    abort 'Run `gem install rspec` to install RSpec'
+  end
+end
+
+task :default => :spec

data/TODO.md

@@ -1,7 +1,12 @@
-# TODO
-
-* Info about xoauth and plain authentication in readme
-* Specs for xoauth 
-* Specs for message operations
-* Specs for filters in mailbox
-* Non-English accounts
+# TODO
+
+* Specs for xoauth 
+* Specs for message operations
+* Specs for filters in mailbox
+* Specs for current [Gmail IMAP extensions](http://code.google.com/apis/gmail/imap/)
+* Non-English accounts
+* Further implement [Gmail IMAP extensions](http://code.google.com/apis/gmail/imap/)
+  * add custom search (X-GM-RAW)
+  * add thread id (X-GM-THRID)
+* Export/Import to mbox format
+* Integration with [contacts](http://rubygems.org/gems/contacts) gem

data/gmail.gemspec

@@ -1,23 +1,34 @@
-# -*- ruby -*-
-$:.unshift(File.expand_path('../lib', __FILE__))
-require 'gmail/version'
-
-Gem::Specification.new do |s|
-  s.name             = 'gmail'
-  s.version          = Gmail.version
-  s.homepage         = 'http://github.com/nu7hatch/gmail'
-  s.email            = ['chris@nu7hat.ch']
-  s.authors          = ['BehindLogic', 'Chris Kowalik']
-  s.summary          = %q{A Rubyesque interface to Gmail, with all the tools you will need.}
-  s.description      = %q{A Rubyesque interface to Gmail, with all the tools you will need. Search, read and send multipart emails; archive, mark as read/unread, delete emails; and manage labels.}
-  s.files            = `git ls-files`.split("\n")
-  s.test_files       = `git ls-files -- {spec}/*`.split("\n")
-  s.require_paths    = %w[lib]
-  s.extra_rdoc_files = %w[LICENSE README.md CHANGELOG.md TODO.md]
-
-  s.add_runtime_dependency     'mime', '>= 0.1'
-  s.add_runtime_dependency     'mail', '>= 2.2.1'
-  s.add_runtime_dependency     'gmail_xoauth', '>= 0.3.0'
-  s.add_development_dependency 'rspec', '~> 2.0'
-  s.add_development_dependency 'mocha', '>= 0.9'
-end
+# -*- encoding: utf-8 -*-
+
+$:.push File.expand_path('../lib', __FILE__)
+require 'gmail/version'
+
+Gem::Specification.new do |s|
+  s.name = "gmail"
+  s.summary = "A Rubyesque interface to Gmail, with all the tools you will need."
+  s.description = "A Rubyesque interface to Gmail, with all the tools you will need.
+  Search, read and send multipart emails; archive, mark as read/unread,
+  delete emails; and manage labels.
+  "
+  s.version = Gmail::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.authors = ["Chris Kowalik"]
+  s.email = ["chris@nu7hat.ch"]
+  s.homepage = "http://github.com/nu7hatch/gmail"
+  
+  # runtime dependencies
+  s.add_dependency "mime", ">= 0.1"
+  s.add_dependency "mail", ">= 2.2.1"
+  s.add_dependency "gmail_xoauth", ">= 0.3.0"
+  
+  # development dependencies
+  s.add_development_dependency "rake"
+  s.add_development_dependency "rspec", "~> 2.0"
+  s.add_development_dependency "mocha", ">= 0.9"
+  s.add_development_dependency "gem-release"
+  
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/gmail.rb

@@ -1,82 +1,65 @@
-require 'net/imap'
-require 'net/smtp'
-require 'mail'
-require 'date'
-require 'time'
-
-if RUBY_VERSION < "1.8.7"
-  require "smtp_tls"
-end
-
-class Object
-  def to_imap_date
-    Date.parse(to_s).strftime("%d-%B-%Y")
-  end
-end
-
-module Gmail
-  autoload :Version, "gmail/version"
-  autoload :Client,  "gmail/client"
-  autoload :Labels,  "gmail/labels"
-  autoload :Mailbox, "gmail/mailbox"
-  autoload :Message, "gmail/message"
-
-  class << self
-
-    # Creates new Gmail connection using given authorization options.
-    #
-    # ==== Examples
-    #
-    #   Gmail.new(:plain, "foo@gmail.com", "password")
-    #   Gmail.new(:xoauth, "foo@gmail.com", 
-    #     :consumer_key => "",
-    #     :consumer_secret => "",
-    #     :token => "",
-    #     :secret => "")
-    #
-    # To use plain authentication mehod you can also call:
-    #
-    #   Gmail.new("foo@gmail.com", "password")
-    #
-    # You can also use block-style call:
-    #
-    #   Gmail.new("foo@gmail.com", "password") do |client|
-    #     # ...
-    #   end
-    #
-    def new(*args, &block)
-      client = connect_with_proper_client(*args)
-      client.connect and client.login
-      perform_block(client, &block)
-    end
-    alias :connect :new
-
-    def new!(*args, &block)
-      client = connect_with_proper_client(*args)
-      client.connect! and client.login!
-      perform_block(client, &block)
-    end
-    alias :connect! :new!
-    
-    protected
-
-    def connect_with_proper_client(*args)
-      if args.first.is_a?(Symbol)        
-        login_method = args.shift  
-      else
-        login_method ||= :plain
-      end
-
-      Client.send("new_#{login_method}", *args)
-    end
-
-    def perform_block(client, &block)
-      if block_given?
-        yield client
-        client.logout
-      end
-      client
-    end
-
-  end # << self
-end # Gmail
+require 'net/imap'
+require 'net/smtp'
+require 'mail'
+require 'date'
+require 'time'
+
+if RUBY_VERSION < "1.8.7"
+  require "smtp_tls"
+end
+
+class Object
+  def to_imap_date
+    Date.parse(to_s).strftime("%d-%B-%Y")
+  end
+end
+
+module Gmail
+  autoload :Version, "gmail/version"
+  autoload :Client,  "gmail/client"
+  autoload :Labels,  "gmail/labels"
+  autoload :Mailbox, "gmail/mailbox"
+  autoload :Message, "gmail/message"
+
+  class << self
+    # Creates new Gmail connection using given authorization options.
+    #
+    # ==== Examples
+    #
+    #   Gmail.new(:plain, "foo@gmail.com", "password")
+    #   Gmail.new(:xoauth, "foo@gmail.com", 
+    #     :consumer_key => "",
+    #     :consumer_secret => "",
+    #     :token => "",
+    #     :secret => "")
+    #
+    # To use plain authentication mehod you can also call:
+    #
+    #   Gmail.new("foo@gmail.com", "password")
+    #
+    # You can also use block-style call:
+    #
+    #   Gmail.new("foo@gmail.com", "password") do |client|
+    #     # ...
+    #   end
+    #
+
+    ['', '!'].each { |kind|
+      define_method("new#{kind}") do |*args, &block|                  # def new(*args, &block)
+        args.unshift(:plain) unless args.first.is_a?(Symbol)          #   args.unshift(:plain) unless args.first.is_a?(Symbol)  
+        client = Gmail::Client.new(*args)                             #   client = Gmail::Client.new(*args) 
+        client.send("connect#{kind}") and client.send("login#{kind}") #   client.connect and client.login
+                                                                      #  
+        if block_given?                                               #   if block_given?
+          yield client                                                #     yield client
+          client.logout                                               #     client.logout
+        end                                                           #   end
+                                                                      #   
+        client                                                        #   client
+      end                                                             # end
+    }
+
+    alias :connect :new
+    alias :connect! :new!
+  end # << self
+end # Gmail

data/lib/gmail/client.rb

@@ -1,22 +1,30 @@
-module Gmail
-  module Client
-    # Raised when connection with GMail IMAP service couldn't be established. 
-    class ConnectionError < SocketError; end
-    # Raised when given username or password are invalid.
-    class AuthorizationError < Net::IMAP::NoResponseError; end
-    # Raised when delivered email is invalid. 
-    class DeliveryError < ArgumentError; end
-    
-    autoload :Base,   'gmail/client/base'
-    autoload :Plain,  'gmail/client/plain'
-    autoload :XOAuth, 'gmail/client/xoauth'
-
-    def self.new_plain(*args)
-      Gmail::Client::Plain.new(*args)
-    end
-
-    def self.new_xoauth(*args)
-      Gmail::Client::XOAuth.new(*args)
-    end
-  end # Client
-end # Gmail
+module Gmail
+  module Client
+    # Raised when connection with GMail IMAP service couldn't be established. 
+    class ConnectionError < SocketError; end
+    # Raised when given username or password are invalid.
+    class AuthorizationError < Net::IMAP::NoResponseError; end
+    # Raised when delivered email is invalid. 
+    class DeliveryError < ArgumentError; end
+    # Raised when given client is not registered
+    class UnknownClient < ArgumentError; end
+
+    def self.register(name, klass)
+      @clients ||= {}
+      @clients[name] = klass
+    end
+
+    def self.new(name, *args)
+      if client = @clients[name]
+        client.new(*args)
+      else
+        raise UnknownClient, "No such client: #{name}" 
+      end
+    end
+
+    require 'gmail/client/imap_extensions'
+    require 'gmail/client/base'
+    require 'gmail/client/plain'
+    require 'gmail/client/xoauth'
+  end # Client
+end # Gmail

data/lib/gmail/client/base.rb

@@ -1,220 +1,225 @@
-require 'thread'
-
-module Gmail
-  module Client
-    class Base
-      # GMail IMAP defaults
-      GMAIL_IMAP_HOST = 'imap.gmail.com'
-      GMAIL_IMAP_PORT = 993
-      
-      # GMail SMTP defaults
-      GMAIL_SMTP_HOST = "smtp.gmail.com"
-      GMAIL_SMTP_PORT = 587
-      
-      attr_reader :username
-      attr_reader :options
-      
-      def initialize(username, options={})
-        defaults       = {}
-        @username      = fill_username(username)
-        @options       = defaults.merge(options)
-        @mailbox_mutex = Mutex.new
-      end
-      
-      # Connect to gmail service. 
-      def connect(raise_errors=false)
-        @imap = Net::IMAP.new(GMAIL_IMAP_HOST, GMAIL_IMAP_PORT, true, nil, false)
-      rescue SocketError
-        raise_errors and raise ConnectionError, "Couldn't establish connection with GMail IMAP service"
-      end
-      
-      # This version of connect will raise error on failure...
-      def connect!
-        connect(true)
-      end
-      
-      # Return current connection. Log in automaticaly to specified account if 
-      # it is necessary.
-      def connection
-        login and at_exit { logout } unless logged_in?
-        @imap
-      end
-      alias :conn :connection
-      
-      # Login to specified account.
-      def login(*args)
-        raise NotImplementedError, "The `#{self.class.name}#login` method is not implemented."
-      end
-      alias :sign_in :login
-      
-      # This version of login will raise error on failure...
-      def login!
-        login(true)
-      end
-      alias :sign_in! :login!
-      
-      # Returns +true+ when you are logged in to specified account.
-      def logged_in?
-        !!@logged_in
-      end
-      alias :signed_in? :logged_in?
-      
-      # Logout from GMail service. 
-      def logout
-        @imap && logged_in? and @imap.logout
-      ensure
-        @logged_in = false
-      end
-      alias :sign_out :logout
-      
-      # Return labels object, which helps you with managing your GMail labels.
-      # See <tt>Gmail::Labels</tt> for details.
-      def labels
-        @labels ||= Labels.new(conn)
-      end
-      
-      # Compose new e-mail.
-      #
-      # ==== Examples
-      #   
-      #   mail = gmail.compose
-      #   mail.from "test@gmail.org"
-      #   mail.to "friend@gmail.com"
-      #
-      # ... or block style:
-      #  
-      #   mail = gmail.compose do 
-      #     from "test@gmail.org"
-      #     to "friend@gmail.com"
-      #     subject "Hello!"
-      #     body "Hello my friend! long time..."
-      #   end
-      #
-      # Now you can deliver your mail:
-      #
-      #   gmail.deliver(mail)
-      def compose(mail=nil, &block)
-        if block_given?
-          mail = Mail.new(&block)
-        elsif !mail 
-          mail = Mail.new
-        end 
-
-        mail.delivery_method(*smtp_settings)
-        mail.from = username unless mail.from
-        mail
-      end
-      alias :message :compose
-      
-      # Compose (optionaly) and send given email. 
-      #
-      # ==== Examples
-      #
-      #   gmail.deliver do 
-      #     to "friend@gmail.com"
-      #     subject "Hello friend!"
-      #     body "Hi! How are you?"
-      #   end
-      #
-      # ... or with already created message:
-      #
-      #   mail = Mail.new { ... }
-      #   gmail.deliver(mail)
-      #
-      #   mail = gmail.compose { ... }
-      #   gmail.deliver(mail)
-      def deliver(mail=nil, raise_errors=false, &block)
-        mail = compose(mail, &block) if block_given?
-        mail.deliver!
-      rescue Object => ex
-        raise_errors and raise DeliveryError, "Couldn't deliver email: #{ex.to_s}"
-      end
-      
-      # This version of deliver will raise error on failure...
-      def deliver!(mail=nil, &block)
-        deliver(mail, true, &block)
-      end
-      
-      # Do something with given mailbox or within it context. 
-      #
-      # ==== Examples
-      #
-      #   mailbox = gmail.mailbox("INBOX")
-      #   mailbox.emails(:all)
-      #   mailbox.count(:unread, :before => Time.now-(20*24*3600))
-      #
-      # ... or block style:
-      #
-      #   gmail.label("Work") do |mailbox|
-      #     mailbox.emails(:unread)
-      #     mailbox.count(:all)
-      #     ...
-      #   end
-      def mailbox(name, &block)
-        @mailbox_mutex.synchronize do
-          name = Net::IMAP.encode_utf7(name.to_s)
-          mailbox = (mailboxes[name] ||= Mailbox.new(self, name))
-          switch_to_mailbox(name) if @current_mailbox != name
-
-          if block_given?
-            mailbox_stack << @current_mailbox
-            result = block.arity == 1 ? block.call(mailbox) : block.call
-            mailbox_stack.pop
-            switch_to_mailbox(mailbox_stack.last)
-            return result
-          end
-
-          return mailbox
-        end
-      end
-      alias :in_mailbox :mailbox
-      alias :in_label :mailbox
-      alias :label :mailbox
-      
-      # Alias for <tt>mailbox("INBOX")</tt>. See <tt>Gmail::Client#mailbox</tt>
-      # for details.
-      def inbox
-        mailbox("INBOX")
-      end
-      
-      def mailboxes
-        @mailboxes ||= {}
-      end
-      
-      def inspect
-        "#<Gmail::Client#{'0x%04x' % (object_id << 1)} (#{username}) #{'dis' if !logged_in?}connected>"
-      end
-      
-      def fill_username(username)
-        username =~ /@/ ? username : "#{username}@gmail.com"
-      end
-
-      def mail_domain
-        username.split('@')[0]
-      end
-      
-      private
-      
-      def switch_to_mailbox(mailbox)
-        conn.select(mailbox) if mailbox
-        @current_mailbox = mailbox
-      end
-      
-      def mailbox_stack
-        @mailbox_stack ||= []
-      end
-      
-      def smtp_settings
-        [:smtp, {
-          :address => GMAIL_SMTP_HOST,
-          :port => GMAIL_SMTP_PORT,
-          :domain => mail_domain,
-          :user_name => username,
-          :password => password,
-          :authentication => 'plain',
-          :enable_starttls_auto => true
-        }]
-      end
-    end # Base
-  end # Client
-end # Gmail
+require 'thread'
+
+module Gmail
+  module Client
+    class Base
+      # GMail IMAP defaults
+      GMAIL_IMAP_HOST = 'imap.gmail.com'
+      GMAIL_IMAP_PORT = 993
+      
+      # GMail SMTP defaults
+      GMAIL_SMTP_HOST = "smtp.gmail.com"
+      GMAIL_SMTP_PORT = 587
+      
+      attr_reader :username
+      attr_reader :options
+      
+      def initialize(username, options={})
+        defaults       = {}
+        @username      = fill_username(username)
+        @options       = defaults.merge(options)
+        @mailbox_mutex = Mutex.new
+      end
+      
+      # Connect to gmail service. 
+      def connect(raise_errors=false)
+        @imap = Net::IMAP.new(GMAIL_IMAP_HOST, GMAIL_IMAP_PORT, true, nil, false)
+        GmailImapExtensions.patch_net_imap_response_parser
+        @imap
+      rescue SocketError
+        raise_errors and raise ConnectionError, "Couldn't establish connection with GMail IMAP service"
+      end
+      
+      # This version of connect will raise error on failure...
+      def connect!
+        connect(true)
+      end
+      
+      # Return current connection. Log in automaticaly to specified account if 
+      # it is necessary.
+      def connection
+        login and at_exit { logout } unless logged_in?
+        @imap
+      end
+      alias :conn :connection
+      
+      # Login to specified account.
+      def login(*args)
+        raise NotImplementedError, "The `#{self.class.name}#login` method is not implemented."
+      end
+      alias :sign_in :login
+      
+      # This version of login will raise error on failure...
+      def login!
+        login(true)
+      end
+      alias :sign_in! :login!
+      
+      # Returns +true+ when you are logged in to specified account.
+      def logged_in?
+        !!@logged_in
+      end
+      alias :signed_in? :logged_in?
+      
+      # Logout from GMail service. 
+      def logout
+        @imap && logged_in? and @imap.logout
+      ensure
+        @logged_in = false
+      end
+      alias :sign_out :logout
+      
+      # Return labels object, which helps you with managing your GMail labels.
+      # See <tt>Gmail::Labels</tt> for details.
+      def labels
+        @labels ||= Labels.new(conn)
+      end
+      
+      # Compose new e-mail.
+      #
+      # ==== Examples
+      #   
+      #   mail = gmail.compose
+      #   mail.from "test@gmail.org"
+      #   mail.to "friend@gmail.com"
+      #
+      # ... or block style:
+      #  
+      #   mail = gmail.compose do 
+      #     from "test@gmail.org"
+      #     to "friend@gmail.com"
+      #     subject "Hello!"
+      #     body "Hello my friend! long time..."
+      #   end
+      #
+      # Now you can deliver your mail:
+      #
+      #   gmail.deliver(mail)
+      def compose(mail=nil, &block)
+        if block_given?
+          mail = Mail.new(&block)
+        elsif !mail 
+          mail = Mail.new
+        end 
+
+        mail.delivery_method(*smtp_settings)
+        mail.from = username unless mail.from
+        mail
+      end
+      alias :message :compose
+      
+      # Compose (optionaly) and send given email. 
+      #
+      # ==== Examples
+      #
+      #   gmail.deliver do 
+      #     to "friend@gmail.com"
+      #     subject "Hello friend!"
+      #     body "Hi! How are you?"
+      #   end
+      #
+      # ... or with already created message:
+      #
+      #   mail = Mail.new { ... }
+      #   gmail.deliver(mail)
+      #
+      #   mail = gmail.compose { ... }
+      #   gmail.deliver(mail)
+      def deliver(mail=nil, raise_errors=false, &block)
+        mail = compose(mail, &block) if block_given?
+        mail.deliver!
+      rescue Object => ex
+        raise_errors and raise DeliveryError, "Couldn't deliver email: #{ex.to_s}"
+      end
+      
+      # This version of deliver will raise error on failure...
+      def deliver!(mail=nil, &block)
+        deliver(mail, true, &block)
+      end
+      
+      # Do something with given mailbox or within it context. 
+      #
+      # ==== Examples
+      #
+      #   mailbox = gmail.mailbox("INBOX")
+      #   mailbox.emails(:all)
+      #   mailbox.count(:unread, :before => Time.now-(20*24*3600))
+      #
+      # ... or block style:
+      #
+      #   gmail.label("Work") do |mailbox|
+      #     mailbox.emails(:unread)
+      #     mailbox.count(:all)
+      #     ...
+      #   end
+      def mailbox(name, &block)
+        @mailbox_mutex.synchronize do
+          name = name.to_s
+          mailbox = (mailboxes[name] ||= Mailbox.new(self, name))
+          switch_to_mailbox(name) if @current_mailbox != name
+
+          if block_given?
+            mailbox_stack << @current_mailbox
+            result = block.arity == 1 ? block.call(mailbox) : block.call
+            mailbox_stack.pop
+            switch_to_mailbox(mailbox_stack.last)
+            return result
+          end
+
+          return mailbox
+        end
+      end
+      alias :in_mailbox :mailbox
+      alias :in_label :mailbox
+      alias :label :mailbox
+      
+      # Alias for <tt>mailbox("INBOX")</tt>. See <tt>Gmail::Client#mailbox</tt>
+      # for details.
+      def inbox
+        mailbox("INBOX")
+      end
+      
+      def mailboxes
+        @mailboxes ||= {}
+      end
+      
+      def inspect
+        "#<Gmail::Client#{'0x%04x' % (object_id << 1)} (#{username}) #{'dis' if !logged_in?}connected>"
+      end
+      
+      def fill_username(username)
+        username =~ /@/ ? username : "#{username}@gmail.com"
+      end
+
+      def mail_domain
+        username.split('@').last
+      end
+      
+      private
+      
+      def switch_to_mailbox(mailbox)
+        if mailbox
+          mailbox = Net::IMAP.encode_utf7(mailbox)
+          conn.select(mailbox)
+        end
+        @current_mailbox = mailbox
+      end
+      
+      def mailbox_stack
+        @mailbox_stack ||= []
+      end
+      
+      def smtp_settings
+        [:smtp, {
+          :address => GMAIL_SMTP_HOST,
+          :port => GMAIL_SMTP_PORT,
+          :domain => mail_domain,
+          :user_name => username,
+          :password => password,
+          :authentication => 'plain',
+          :enable_starttls_auto => true
+        }]
+      end
+    end # Base
+  end # Client
+end # Gmail