rgrove-larch 1.0.0.2 → 1.0.0.3

data/HISTORY

@@ -0,0 +1,16 @@
+Larch History
+================================================================================
+
+Version 1.0.1 (?)
+  * Much more robust handling of unexpected server disconnects and dropped
+    connections.
+  * Fetch message headers in blocks of up to 1024 at a time rather than all at
+    once, to prevent potential problems with certain servers when a mailbox
+    contains a huge number of messages.
+  * Don't try to trap POSIX signals on platforms that aren't likely to support
+    them, and don't die if the platform sniffing doesn't save us.
+  * Add a new "insane" logging level, which will output all IMAP commands and
+    responses to STDERR.
+
+Version 1.0.0 (2009-03-17)
+  * First release.

data/README.rdoc

@@ -0,0 +1,110 @@
+= Larch
+
+Larch is a tool to copy messages from one IMAP server to another quickly and
+safely. It's smart enough not to copy messages that already exist on the
+destination and robust enough to deal with ornery or misbehaving servers.
+
+Larch is particularly well-suited for copying email to, from, or between Gmail
+accounts.
+
+*Author*::    Ryan Grove (mailto:ryan@wonko.com)
+*Version*::   1.0.0 (2009-03-17)
+*Copyright*:: Copyright (c) 2009 Ryan Grove. All rights reserved.
+*License*::   GPL 2.0 (http://opensource.org/licenses/gpl-2.0.php)
+*Website*::   http://github.com/rgrove/larch
+
+== Installation
+
+Install Larch via RubyGems:
+
+  gem install larch
+
+== Usage
+
+Larch is run from the command line. At a minimum, you must specify a source
+server and a destination server in the form of IMAP URIs. You may also specify
+one or more options:
+
+  larch --from <uri> --to <uri> [options]
+
+For an overview of all available command-line options, run:
+
+  larch --help
+
+Specify a source server and a destination server and Larch will prompt you for
+the necessary usernames and passwords, then sync the contents of the source's
++INBOX+ folder to the destination:
+
+  larch --from imap://mail.example.com --to imap://imap.gmail.com
+
+To connect using SSL, specify a URI beginning with <tt>imaps://</tt>:
+
+  larch --from imaps://mail.example.com --to imaps://imap.gmail.com
+
+If you'd like to sync a folder other than +INBOX+, specify the source and
+destination folders using <tt>--from-folder</tt> and <tt>--to-folder</tt>:
+
+  larch --from imaps://mail.example.com --to imaps://imap.gmail.com \
+    --from-folder "Sent Mail" --to-folder "Sent Mail"
+
+By default Larch will create the specified folder if it doesn't already exist on
+the destination server. To prevent this, add the <tt>--no-create-folder</tt>
+option:
+
+  larch --from imaps://mail.example.com --to imaps://imap.gmail.com \
+    --from-folder "Sent Mail" --to-folder "Sent Mail" --no-create-folder
+
+== Server Support
+
+Larch should work well with any server that properly supports
+IMAP4rev1[http://tools.ietf.org/html/rfc3501], and does its best to get along
+with servers that have buggy, unreliable, or incomplete IMAP implementations.
+
+Larch has been tested on and is known to work well with the following IMAP
+servers:
+
+* Dovecot
+* Gmail
+* Microsoft Exchange 2003
+
+== Known Issues
+
+Larch uses Ruby's Net::IMAP standard library for all IMAP operations. While
+Net::IMAP is generally a very solid library, it contains a bug that can cause a
+deadlock to occur if a connection drops unexpectedly (either due to network
+issues or because the server closed the connection without warning) when the
+server has already begun sending a response and Net::IMAP is waiting to receive
+more data.
+
+If this happens, Net::IMAP will continue waiting forever without passing control
+back to Larch, and you will need to manually kill and restart Larch.
+
+== Credit
+
+The Larch::IMAP class borrows heavily from Sup[http://sup.rubyforge.org] by
+William Morgan, the source code of which should be required reading if you're
+doing anything with IMAP in Ruby.
+
+Larch uses the excellent Trollop[http://trollop.rubyforge.org] command-line
+option parser (also by William Morgan) and the
+HighLine[http://highline.rubyforge.org] command-line IO library (by James Edward
+Gray II).
+
+== License
+
+Copyright (c) 2009 Ryan Grove <ryan@wonko.com>
+
+Licensed under the GNU General Public License version 2.0.
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of version 2.0 of the GNU General Public License as published by the
+Free Software Foundation.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program; if not, visit http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
+or write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+Boston, MA 02111-1307 USA.

data/bin/larch

@@ -74,6 +74,8 @@ EOS
   # Go go go!
   init(options[:verbosity])
 
+  Net::IMAP.debug = true if @log.level == :insane
+
   source = IMAP.new(options[:from], options[:from_user], options[:from_pass],
       :fast_scan   => options[:fast_scan],
       :max_retries => options[:max_retries])

data/lib/larch/logger.rb

@@ -4,11 +4,12 @@ class Logger
   attr_reader :level, :output
 
   LEVELS = {
-    :fatal => 0,
-    :error => 1,
-    :warn  => 2,
-    :info  => 3,
-    :debug => 4
+    :fatal  => 0,
+    :error  => 1,
+    :warn   => 2,
+    :info   => 3,
+    :debug  => 4,
+    :insane => 5
   }
 
   def initialize(level = :info, output = $stdout)

data/lib/larch/version.rb

@@ -1,6 +1,6 @@
 module Larch
   APP_NAME      = 'Larch'
-  APP_VERSION   = '1.0.0'
+  APP_VERSION   = '1.0.0.3'
   APP_AUTHOR    = 'Ryan Grove'
   APP_EMAIL     = 'ryan@wonko.com'
   APP_URL       = 'http://github.com/rgrove/larch/'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rgrove-larch
 version: !ruby/object:Gem::Version 
-  version: 1.0.0.2
+  version: 1.0.0.3
 platform: ruby
 authors: 
 - Ryan Grove
@@ -41,7 +41,9 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- HISTORY
 - LICENSE
+- README.rdoc
 - bin/larch
 - lib/larch.rb
 - lib/larch/errors.rb