ruby-gmail 0.0.3 → 0.0.4

data/History.txt

@@ -1,8 +1,21 @@
-=== 0.0.1 / 2009-11-18
+=== 0.0.4 / 2009-11-30
 
-* 1 major enhancement
+* 4 minor enhancement
 
-  * Birthday!
+  * Added label creation (thanks to Justin Perkins / http://github.com/justinperkins)
+  * Made the gem login automatically when first needed
+  * Added an optional block on the Gmail.new object that will login and logout for you.
+  * Added several search options (thanks to Mikkel Malmberg / http://github.com/mikker)
+
+=== 0.0.3 / 2009-11-19
+
+* 1 bugfix
+
+  * Fixed MIME::Message#content= for messages without an encoding
+
+* 1 minor enhancement
+
+  * Added Gmail#new_message
 
 === 0.0.2 / 2009-11-18
 
@@ -10,9 +23,9 @@
 
   * Made all of the examples in the README possible.
 
-=== 0.0.3 / 2009-11-19
+=== 0.0.1 / 2009-11-18
 
-* 1 minor enhancement
+* 1 major enhancement
+
+  * Birthday!
 
-  * Fixed MIME::Message#content= for messages without an encoding
-  * Added Gmail#new_message

data/Manifest.txt

@@ -10,4 +10,4 @@ lib/mime/message.rb
 lib/smtp_tls.rb
 Manifest.txt
 Rakefile
-README.txt
+README.markdown

data/README.markdown

@@ -0,0 +1,106 @@
+# ruby-gmail
+
+* Homepage: [http://dcparker.github.com/ruby-gmail/](http://dcparker.github.com/ruby-gmail/)
+* Code: [http://github.com/dcparker/ruby-gmail](http://github.com/dcparker/ruby-gmail)
+* Gem: [http://gemcutter.org/gems/ruby-gmail](http://gemcutter.org/gems/ruby-gmail)
+
+## Author(s)
+
+* Daniel Parker of BehindLogic.com
+
+Extra thanks for specific feature contributions from:
+
+  * [Justin Perkins](http://github.com/justinperkins)
+  * [Mikkel Malmberg](http://github.com/mikker)
+
+
+## Description
+
+A Rubyesque interface to Gmail, with all the tools you'll need. Search, read and send multipart emails; archive, mark as read/unread, delete emails; and manage labels.
+
+## Features
+
+* Search emails
+* Read emails (handles attachments)
+* Emails: Label, archive, delete, mark as read/unread/spam
+* Create and delete labels
+* Create and send multipart email messages in plaintext and/or html, with inline images and attachments
+* Utilizes Gmail's IMAP & SMTP, MIME-type detection and parses and generates MIME properly.
+
+## Problems:
+
+* May not correctly read malformed MIME messages. This could possibly be corrected by having IMAP parse the MIME structure.
+* Cannot grab the plain or html message without also grabbing attachments. It might be nice to lazy-[down]load attachments.
+
+## Example Code:
+
+    require 'gmail'
+    gmail = Gmail.new(username, password) do |g|
+      read_count = g.inbox.count(:read) # => .count take the same arguments as .emails
+      unread = g.inbox.emails(:unread)
+      unread[0].archive!
+      unread[1].delete!
+      unread[2].move_to('FunStuff') # => labels and removes from inbox
+      unread[3].message # => a MIME::Message, parsed from the email body
+      unread[3].mark(:read)
+      unread[3].message.attachments.length
+      unread[4].label('FunStuff') # => Just adds the label 'FunStuff'
+      unread[4].message.save_attachments_to('path/to/save/into')
+      unread[5].message.attachments[0].save_to_file('path/to/save/into')
+      unread[6].mark(:spam)
+    end
+
+    # Optionally use a block like above to have the gem automatically login and logout,
+    # or just use it without a block after creating the object like below, and it will
+    # automatically logout at_exit. The block method is recommended in order to limit
+    # your signed-in session.
+
+    older = gmail.inbox.emails(:after => '2009-03-04', :before => '2009-03-15')
+    todays_date = Time.parse(Time.now.strftime('%Y-%m-%d'))
+    yesterday = gmail.inbox.emails(:after => (todays_date - 24*60*60), :before => todays_date)
+    todays_unread = gmail.inbox.emails(:unread, :after => todays_date)
+  
+    new_email = MIME::Message.generate
+    new_email.to "email@example.com"
+    new_email.subject "Having fun in Puerto Rico!"
+    plain, html = new_email.generate_multipart('text/plain', 'text/html')
+    plain.content = "Text of plain message."
+    html.content = "<p>Text of <em>html</em> message.</p>"
+    new_email.attach_file('some_image.dmg')
+    gmail.send_email(new_email)
+
+## Requirements
+
+* ruby
+* net/smtp
+* net/imap
+* shared-mime-info rubygem
+
+## Install
+
+    sudo gem install ruby-gmail -s http://gemcutter.org
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2009 BehindLogic
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -6,6 +6,7 @@ require 'hoe'
 Hoe.spec 'ruby-gmail' do
   developer 'Daniel Parker', 'gems@behindlogic.com'
   extra_deps << ['shared-mime-info', '>= 0']
+  self.readme_file = 'README.markdown'
   self.url = "http://dcparker.github.com/ruby-gmail"
-  self.post_install_message = "If you *really* like this gem, consider donating toward time for me to make it even better: http://pledgie.com/campaigns/7087"
+  self.post_install_message = "\n\033[34mIf ruby-gmail saves you TWO hours of work, want to compensate me for, like, a half-hour?\nSupport me in making new and better gems:\033[0m \033[31;4mhttp://pledgie.com/campaigns/7087\033[0m\n\n"
 end

data/lib/gmail.rb

@@ -3,12 +3,13 @@ require 'net/smtp'
 require 'smtp_tls'
 
 class Gmail
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 
-  attr_reader :imap
+  class NoLabel < RuntimeError; end
 
   def initialize(username, password)
     # This is to hide the username and password, not like it REALLY needs hiding, but ... you know.
+    # Could be helpful when demoing the gem in irb, these bits won't show up that way.
     meta = class << self
       class << self
         attr_accessor :username, :password
@@ -18,8 +19,11 @@ class Gmail
     meta.username = username =~ /@/ ? username : username + '@gmail.com'
     meta.password = password
     @imap = Net::IMAP.new('imap.gmail.com',993,true)
-    @connected = true if @imap.login(username, password)
-    at_exit { logout if @connected }
+    if block_given?
+      @connected = true if @imap.login(username, password)
+      yield self
+      logout
+    end
   end
 
   # Accessors for IMAP things
@@ -31,27 +35,41 @@ class Gmail
   def inbox
     mailbox('inbox')
   end
+  # Accessor for @imap, but ensures that it's logged in first.
+  def imap
+    if !@connected
+      meta = class << self; self end
+      @connected = true if @imap.login(meta.username, meta.password)
+      at_exit { logout if @connected } # Set up auto-logout for later.
+    end
+    @imap
+  end
   # Log out of gmail
   def logout
     @connected = false if @imap.logout
   end
 
+  def create_label(name)
+    imap.create(name)
+  end
+
   def in_mailbox(mailbox, &block)
     raise ArgumentError, "Must provide a code block" unless block_given?
     mailbox_stack << mailbox
     unless @selected == mailbox.name
-      @imap.select(mailbox.name)
+      imap.select(mailbox.name)
       @selected = mailbox.name
     end
     value = block.arity == 1 ? block.call(mailbox) : block.call
     mailbox_stack.pop
     # Select previously selected mailbox if there is one
     if mailbox_stack.last
-      @imap.select(mailbox_stack.last.name)
+      imap.select(mailbox_stack.last.name)
       @selected = mailbox.name
     end
     return value
   end
+  alias :in_label :in_mailbox
 
   def open_smtp(&block)
     raise ArgumentError, "This method is to be used with a block." unless block_given?

data/lib/gmail/mailbox.rb

@@ -1,3 +1,11 @@
+require 'date'
+require 'time'
+class Object
+  def to_imap_date
+    Date.parse(to_s).strftime("%d-%B-%Y")
+  end
+end
+
 class Gmail
   class Mailbox
     attr_reader :name
@@ -17,18 +25,45 @@ class Gmail
 
     # Method: emails
     # Args: [ :all | :unread | :read ]
-    def emails(key = :all)
-      aliases = {
-        :all => ['ALL'],
-        :unread => ['UNSEEN'],
-        :read => ['SEEN']
-      }
+    # Opts: {:since => Date.new}
+    def emails(key_or_opts = :all, opts={})
+      if key_or_opts.is_a?(Hash) && opts.empty?
+        search = ['ALL']
+        opts = key_or_opts
+      elsif key_or_opts.is_a?(Symbol) && opts.is_a?(Hash)
+        aliases = {
+          :all => ['ALL'],
+          :unread => ['UNSEEN'],
+          :read => ['SEEN']
+        }
+        search = aliases[key_or_opts]
+      elsif key_or_opts.is_a?(Array) && opts.empty?
+        search = key_or_opts
+      else
+        raise ArgumentError, "Couldn't make sense of arguments to #emails - should be an optional hash of options preceded by an optional read-status bit; OR simply an array of parameters to pass directly to the IMAP uid_search call."
+      end
+      if !opts.empty?
+        # Support for several search macros
+        # :before => Date, :on => Date, :since => Date, :from => String, :to => String
+        search.concat ['SINCE', opts[:after].to_imap_date] if opts[:after]
+        search.concat ['BEFORE', opts[:before].to_imap_date] if opts[:before]
+        search.concat ['ON', opts[:on].to_imap_date] if opts[:on]
+        search.concat ['FROM', opts[:from]] if opts[:from]
+        search.concat ['TO', opts[:to]] if opts[:to]
+      end
+
       # puts "Gathering #{(aliases[key] || key).inspect} messages for mailbox '#{name}'..."
       @gmail.in_mailbox(self) do
-        @gmail.imap.uid_search(aliases[key] || key).collect { |uid| messages[uid] ||= Message.new(@gmail, self, uid) }
+        @gmail.imap.uid_search(search).collect { |uid| messages[uid] ||= Message.new(@gmail, self, uid) }
       end
     end
 
+    # This is a convenience method that really probably shouldn't need to exist, but it does make code more readable
+    # if seriously all you want is the count of messages.
+    def count(*args)
+      emails(*args).length
+    end
+
     def messages
       @messages ||= {}
     end

data/lib/gmail/message.rb

@@ -64,7 +64,22 @@ class Gmail
     end
     def label(name)
       @gmail.in_mailbox(@mailbox) do
-        @gmail.imap.uid_copy(uid, name)
+        begin
+          @gmail.imap.uid_copy(uid, name)
+        rescue Net::IMAP::NoResponseError
+          raise Gmail::NoLabel, "No label `#{name}' exists!"
+        end
+      end
+    end
+    def label!(name)
+      @gmail.in_mailbox(@mailbox) do
+        begin
+          @gmail.imap.uid_copy(uid, name)
+        rescue Net::IMAP::NoResponseError
+          # need to create the label first
+          @gmail.create_label(name)
+          retry
+        end
       end
     end
     # We're not sure of any 'labels' except the 'mailbox' we're in at the moment.

data/lib/mime/entity.rb

@@ -89,11 +89,12 @@ module MIME
       end
     end
     def attachment?
-      headers['content-disposition'] =~ /^attachment(?=;|$)/
+      headers['content-disposition'] =~ /^attachment(?=;|$)/ || headers['content-disposition'] =~ /^form-data;.* filename=[\"\']?[^\"\']+[\"\']?/
     end
-    def attachment_filename
+    alias :file? :attachment?
+    def part_filename
       # Content-Disposition: attachment; filename="summary.txt"
-      if headers['content-disposition'] =~ /^attachment; filename=[\"\']?([^\"\']+)/
+      if headers['content-disposition'] =~ /; filename=[\"\']?([^\"\']+)/
         $1
       end
     end
@@ -120,8 +121,8 @@ module MIME
 
     def save_to_file(path=nil)
       filename = path if path && !File.exists?(path) # If path doesn't exist, assume it's a filename
-      filename ||= path + '/' + attachment_filename if path && attachment? # If path does exist, and we're saving an attachment, use the attachment filename
-      filename ||= (attachment? ? attachment_filename : path) # If there is no path and we're saving an attachment, use the attachment filename; otherwise use path (whether it is present or not)
+      filename ||= path + '/' + part_filename if path && attachment? # If path does exist, and we're saving an attachment, use the attachment filename
+      filename ||= (attachment? ? part_filename : path) # If there is no path and we're saving an attachment, use the attachment filename; otherwise use path (whether it is present or not)
       filename ||= '.' # No path supplied, and not saving an attachment. We'll just save it in the current directory.
       if File.directory?(filename)
         i = 0

data/lib/mime/message.rb

@@ -28,6 +28,15 @@ module MIME
       find_parts(:content_disposition => 'attachment')
     end
 
+    def text
+      part = find_part(:content_type => 'text/plain')
+      part.content if part
+    end
+    def html
+      part = find_part(:content_type => 'text/html')
+      part.content if part
+    end
+
     def save_attachments_to(path=nil)
       attachments.each {|a| a.save_to_file(path) }
     end

data/lib/smtp_tls.rb

@@ -15,13 +15,13 @@ Net::SMTP.class_eval do
     start_method = use_tls ? :do_tls_start : :do_start
     if block_given?
       begin
-        send start_method, helo, user, secret, authtype
+        send(start_method, helo, user, secret, authtype)
         return yield(self)
       ensure
         do_finish
       end
     else
-      send start_method helo, user, secret, authtype
+      send(start_method, helo, user, secret, authtype)
       return self
     end
   end
@@ -31,9 +31,9 @@ Net::SMTP.class_eval do
   def do_tls_start(helodomain, user, secret, authtype)
     raise IOError, 'SMTP session already started' if @started
     if RUBY_VERSION == '1.8.6'
-      check_auth_args user, secret, authtype if user or secret
+      check_auth_args(user, secret, authtype) if user or secret
     else
-      check_auth_args user, secret if user or secret
+      check_auth_args(user, secret) if user or secret
     end
 
     sock = timeout(@open_timeout) { TCPSocket.open(@address, @port) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-gmail
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Daniel Parker
@@ -30,7 +30,7 @@ cert_chain:
   teST6sOe8lUhZQ==
   -----END CERTIFICATE-----
 
-date: 2009-11-20 00:00:00 -05:00
+date: 2009-12-10 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -53,7 +53,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 2.3.3
     version: 
-description: A Rubyesque interface to Gmail. Connect to Gmail via IMAP and manipulate emails and labels. Send email with your Gmail account via SMTP. Includes full support for parsing and generating MIME messages.
+description: A Rubyesque interface to Gmail, with all the tools you'll need. Search, read and send multipart emails; archive, mark as read/unread, delete emails; and manage labels.
 email: 
 - gems@behindlogic.com
 executables: []
@@ -63,7 +63,6 @@ extensions: []
 extra_rdoc_files: 
 - History.txt
 - Manifest.txt
-- README.txt
 files: 
 - .autotest
 - History.txt
@@ -77,15 +76,17 @@ files:
 - lib/smtp_tls.rb
 - Manifest.txt
 - Rakefile
-- README.txt
+- README.markdown
 has_rdoc: true
 homepage: http://dcparker.github.com/ruby-gmail
 licenses: []
 
-post_install_message: "If you *really* like this gem, consider donating toward time for me to make it even better: http://pledgie.com/campaigns/7087"
+post_install_message: "\n\
+  \e[34mIf ruby-gmail saves you TWO hours of work, want to compensate me for, like, a half-hour?\n\
+  Support me in making new and better gems:\e[0m \e[31;4mhttp://pledgie.com/campaigns/7087\e[0m\n\n"
 rdoc_options: 
 - --main
-- README.txt
+- README.markdown
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -106,6 +107,6 @@ rubyforge_project: ruby-gmail
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: A Rubyesque interface to Gmail
+summary: A Rubyesque interface to Gmail, with all the tools you'll need
 test_files: []
 

data/README.txt

@@ -1,85 +0,0 @@
-= ruby-gmail
-
-* Homepage: http://dcparker.github.com/ruby-gmail/
-* Code: http://github.com/dcparker/ruby-gmail
-
-
-== DESCRIPTION:
-
-A Rubyesque interface to Gmail. Connect to Gmail via IMAP and manipulate emails and labels. Send email with your Gmail account via SMTP. Includes full support for parsing and generating MIME messages.
-
-== FEATURES:
-
-* Read emails via IMAP
-* Full MIME parsing ability, with understanding of attachments
-* Create, rename, and delete labels
-* Label, archive, delete, mark as read/unread/spam
-* Send emails via SMTP
-* Full ability to generate MIME messages including inline images and attachments
-
-== PROBLEMS:
-
-* May not correctly read malformed MIME messages. This could possibly be corrected by having IMAP parse the MIME structure.
-* Cannot grab the plain or html message without also grabbing attachments. It might be nice to lazy-[down]load attachments.
-
-== SYNOPSIS:
-
-  require 'gmail'
-  gmail = Gmail.new(username, password)
-  gmail.inbox.count # => {:read => 41, :unread => 2}
-  unread = gmail.inbox.emails(:unread)
-  unread[0].archive!
-  unread[1].delete!
-  unread[2].move_to('FunStuff') # => Labels 'FunStuff' and removes from inbox
-  unread[3].message # => a MIME::Message, parsed from the email body
-  unread[3].mark(:read)
-  unread[3].message.attachments.length
-  unread[4].label('FunStuff') # => Just adds the label 'FunStuff'
-  unread[4].message.save_attachments_to('path/to/save/into')
-  unread[5].message.attachments[0].save_to_file('path/to/save/into')
-  unread[6].mark(:spam)
-  
-  new_email = MIME::Message.generate
-  new_email.to "email@example.com"
-  new_email.subject "Having fun in Puerto Rico!"
-  plain, html = new_email.generate_multipart('text/plain', 'text/html')
-  plain.content = "Text of plain message."
-  html.content = "<p>Text of <em>html</em> message.</p>"
-  new_email.attach_file('some_image.dmg')
-  gmail.send_email(new_email)
-
-== REQUIREMENTS:
-
-* ruby
-* net/smtp
-* net/imap
-* gem shared-mime-info
-
-== INSTALL:
-
-* [sudo] gem install ruby-gmail -s http://gemcutter.org
-
-== LICENSE:
-
-(The MIT License)
-
-Copyright (c) 2009 BehindLogic.com
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.