gmail 0.3.0

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+*.rdb

data/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Gmail gem changelog
+
+## 0.3.0 / Unreleased
+
+* Refactoring
+* Fixed bugs
+* API improvements
+* Better documentation
+* Code cleanup
+* RSpec for everything
+
+## 0.1.1 / 2010-05-11
+
+* Added explicit tmail dependency in gemspec
+* Added better README tutorial content
+
+## 0.0.9 / 2010-04-17
+
+* Fixed content-transfer-encoding when sending email
+
+## 0.0.8 / 2009-12-23
+
+* Fixed attaching a file to an empty message
+
+## 0.0.7 / 2009-12-23
+
+* Improved multipart message parsing reliability
+
+## 0.0.6 / 2009-12-21
+
+* Fixed multipart parsing for when the boundary is marked in quotes.
+
+## 0.0.5 / 2009-12-16
+
+* Fixed IMAP initializer to work with Ruby 1.9's net/imap
+* Better logout depending on the IMAP connection itself
+* Added MIME::Message#text and MIME::Message#html for easier access to an email body
+* Improved the MIME-parsing API slightly
+* Added some tests
+
+## 0.0.4 / 2009-11-30
+
+* 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
+
+* Fixed MIME::Message#content= for messages without an encoding
+* Added Gmail#new_message
+
+## 0.0.2 / 2009-11-18
+
+* Made all of the examples in the README possible
+
+## 0.0.1 / 2009-11-18
+
+* Birthday!
+

data/LICENSE

@@ -0,0 +1,21 @@
+Copyrignt (c) 2010 Kriss 'nu7hatch' Kowalik
+Copyright (c) 2009-2010 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/README.md

@@ -0,0 +1,247 @@
+# GMail for Ruby
+
+A Rubyesque interface to Google's GMail, with all the tools you'll need. Search, 
+read and send multipart emails, archive, mark as read/unread, delete emails, 
+and manage labels.
+
+It's based on Daniel Parker's ruby-gmail gem. This version has more friendy
+API, is well tested, better documented and have many other improvements.  
+
+## Author(s)
+
+* Kriss 'nu7hatch' Kowalik
+* [Daniel Parker of BehindLogic.com](http://github.com/dcparker)
+
+Extra thanks for specific feature contributions from:
+
+* [Justin Perkins](http://github.com/justinperkins)
+* [Mikkel Malmberg](http://github.com/mikker)
+* [Julien Blanchard](http://github.com/julienXX)
+* [Federico Galassi](http://github.com/fgalassi)
+
+## Installation
+
+You can install it easy using rubygems:
+
+    sudo gem install gmail
+    
+Or install it manualy:
+
+    git clone git://github.com/nu7hatch/gmail.git
+    cd gmail
+    rake install
+
+To install gmail gem you have to met following requirements (with rubygems all 
+will be installed automatically):
+
+* mail
+* mime
+* smpt_tls (Ruby < 1.8.7)
+
+## Features
+
+* Search emails
+* Read emails (handles attachments)
+* Emails: label, archive, delete, mark as read/unread/spam, star
+* Manage 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.
+
+## Basic usage
+
+First of all require the `gmail` library.
+
+    require 'gmail'
+    
+### Authenticating gmail sessions
+
+This will you automatically log in to your account. 
+
+    gmail = Gmail.connect(username, password)
+    # play with your gmail...
+    gmail.logout
+
+If you pass a block, the session will be passed into the block, and the session 
+will be logged out after the block is executed.
+
+    Gmail.connect(username, password) do |gmail|
+      # play with your gmail...
+    end
+    
+Examples above are "quiet", it means that it will not raise any errors when 
+session couldn't be started (eg. because of connection error or invalid 
+authorization data). You can use connection which handles errors raising:
+
+    Gmail.connect!(username, password)
+    Gmail.connect!(username, password) {|gmail| ... play with gmail ... }
+    
+You can also check if you are logged in at any time:
+
+    Gmail.connect(username, password) do |gmail|
+      gmail.logged_in?
+    end
+
+### Counting and gathering emails
+    
+Get counts for messages in the inbox:
+
+    gmail.inbox.count
+    gmail.inbox.count(:unread)
+    gmail.inbox.count(:read)
+
+Count with some criteria:
+
+    gmail.inbox.count(:after => Date.parse("2010-02-20"), :before => Date.parse("2010-03-20"))
+    gmail.inbox.count(:on => Date.parse("2010-04-15"))
+    gmail.inbox.count(:from => "myfriend@gmail.com")
+    gmail.inbox.count(:to => "directlytome@gmail.com")
+
+Combine flags and options:
+
+    gmail.inbox.count(:unread, :from => "myboss@gmail.com")
+    
+Browsing labeled emails is similar to work with inbox.
+
+    gmail.mailbox('Urgent').count
+    
+Getting messages works the same way as counting: Remember that every message in a 
+conversation/thread will come as a separate message.
+
+    gmail.inbox.emails(:unread, :before => Date.parse("2010-04-20"), :from => "myboss@gmail.com")
+
+You can use also one of aliases:
+
+    gmail.inbox.find(...)
+    gmail.inbox.search(...)
+    gmail.inbox.mails(...)    
+    
+Also you can manipulate each message using block style:
+
+    gmail.inbox.find(:unread) do |email|
+      email.read!
+    end
+    
+### Working with emails!
+
+Any news older than 4-20, mark as read and archive it:
+
+    gmail.inbox.find(:before => Date.parse("2010-04-20"), :from => "news@nbcnews.com") do |email|
+      email.read! # can also unread!, spam! or star!
+      email.archive!
+    end
+
+Delete emails from X:
+
+    gmail.inbox.find(:from => "x-fiance@gmail.com").each do |email|
+      email.delete!
+    end
+
+Save all attachments in the "Faxes" label to a local folder:
+
+    folder = "/where/ever"
+    gmail.mailbox("Faxes").emails do |email|
+      if !email.message.attachments.empty?
+        email.message.save_attachments_to(folder)
+      end
+    end
+     
+You can use also `#label` method instead of `#mailbox`: 
+
+    gmail.label("Faxes").emails {|email| ... }
+
+Save just the first attachment from the newest unread email (assuming pdf):
+
+    email = gmail.inbox.find(:unread).first
+    email.attachments[0].save_to_file("/path/to/location")
+
+Add a label to a message:
+
+    email.label("Faxes")
+    
+Example above will raise error when you don't have the `Faxes` label. You can 
+avoid this using:
+
+    email.label!("Faxes") # The `Faxes` label will be automatically created now
+
+You can also move message to a label/mailbox:
+ 
+    email.move_to("Faxes")
+    email.move_to!("NewLabel")
+    
+There is also few shortcuts to mark messages quickly:
+
+    email.read!
+    email.unread!
+    email.spam!
+    email.star!
+    email.unstar!
+
+### Managing labels
+
+With Gmail gem you can also manage your labels. You can get list of defined 
+labels:
+
+    gmail.labels.all
+
+Create new label:
+  
+    gmail.labels.new("Uregent")
+    gmail.labels.add("AnotherOne")
+    
+Remove labels:
+
+    gmail.labels.delete("Uregent")
+    
+Or check if given label exists:
+
+    gmail.labels.exists?("Uregent") # => false
+    gmail.labels.exists?("AnotherOne") # => true
+
+### Composing and sending emails
+
+Creating emails now uses the amazing [Mail](http://rubygems.org/gems/mail) rubygem. 
+See its [documentation here](http://github.com/mikel/mail). The Ruby Gmail will 
+automatically configure your Mail emails to be sent via your Gmail account's SMTP, 
+so they will be in your Gmail's "Sent" folder. Also, no need to specify the "From" 
+email either, because ruby-gmail will set it for you.
+
+    gmail.deliver do
+      to "email@example.com"
+      subject "Having fun in Puerto Rico!"
+      text_part do
+        body "Text of plaintext message."
+      end
+      html_part do
+        body "<p>Text of <em>html</em> message.</p>"
+      end
+      add_file "/path/to/some_image.jpg"
+    end
+
+Or, generate the message first and send it later
+
+    email = gmail.generate_message do
+      to "email@example.com"
+      subject "Having fun in Puerto Rico!"
+      body "Spent the day on the road..."
+    end
+    email.deliver! # or: gmail.deliver(email)
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyrignt (c) 2010 Kriss 'nu7hatch' Kowalik
+Copyright (c) 2009-2010 BehindLogic
+
+See LICENSE for details.
+

data/Rakefile

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+
+begin
+  require 'jeweler'
+  
+  Jeweler::Tasks.new do |gem|
+    gem.name = "gmail"
+    gem.summary = %Q{A Rubyesque interface to Gmail, with all the tools you'll need.}
+    gem.description = <<-DESCR
+      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.
+    DESCR
+    gem.email = "kriss.kowalik@gmail.com"
+    gem.homepage = "http://github.com/nu7hatch/gmail"
+    gem.authors = ["BehindLogic", "Kriss 'nu7hatch' Kowalik"]
+    gem.add_dependency 'mime', '>= 0.1'
+    gem.add_dependency 'mail', '>= 2.2.1'
+    gem.add_development_dependency 'rspec', '~> 2.0'
+    gem.add_development_dependency 'mocha', '>= 0.9'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+  t.rspec_opts = %q[--colour --backtrace]
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |t|
+  t.rcov = true
+  t.rspec_opts = %q[--colour --backtrace]
+  t.rcov_opts = %q[--exclude "spec" --text-report]
+end
+
+task :spec => :check_dependencies
+task :rcov => :check_dependencies
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Ruby GMail #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO.md

@@ -0,0 +1,5 @@
+# TODO
+
+* Specs for message operations
+* Specs for filters in mailbox
+* Non-English accounts

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/gmail.rb

@@ -0,0 +1,47 @@
+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
+    def new(username, password, options={}, &block)
+      client = Client.new(username, password, options)
+      client.connect and client.login
+      if block_given?
+        yield client
+        client.logout
+      end
+      client
+    end
+    alias :connect :new
+    
+    def new!(username, password, options={}, &block)
+      client = Client.new(username, password, options)
+      client.connect! and client.login!
+      if block_given?
+        yield client
+        client.logout
+      end
+      client
+    end
+    alias :connect! :new!
+  end # << self
+end # Gmail