maildir 0.2.0 → 0.3.0

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Aaron Suggs
+Copyright (c) 2010 Aaron Suggs
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -2,8 +2,106 @@
 
 A ruby library for reading and writing messages in the maildir format.
 
-See http://cr.yp.to/proto/maildir.html
+== What's so great about the maildir format
+
+See http://cr.yp.to/proto/maildir.html and http://en.wikipedia.org/wiki/Maildir
+
+As Daniel J. Berstein puts it: "Two words: no locks." The maildir format allows multiple processes to read and write arbitrary messages without file locks.
+
+New messages are initially written to a "tmp" directory with an automatically-generated unique filename. After the message is written, it's moved to the "new" directory where other processes may read it.
+
+While the maildir format was created for email, it works well for arbitrary data. This library can read & write email messages or arbitrary data. See Pluggable serializers for more.
+
+== Install
+
+ sudo gem install maildir
+
+== Usage
+
+Create a maildir in /home/aaron/mail
+
+  maildir = Maildir.new("/home/aaron/mail") # creates tmp, new, and cur dirs
+  # call Maildir.new("/home/aaron/mail", false) to skip directory creation.
+
+Add a new message. This creates a new file with the contents "Hello World!"; returns the path fragment to the file. Messages are written to the tmp dir then moved to new.
+
+  message = maildir.add("Hello World!")
+
+List new messages
+
+  maildir.list(:new) # => [message]
+
+Move the message from "new" to "cur" to indicate that some process has retrieved the message.
+
+  message.process
+
+Indeed, the message is in cur, not new.
+
+  maildir.list(:new) # => []
+  maildir.list(:cur) # => [message]
+
+Add some flags to the message to indicate state. See "What can I put in info" at http://cr.yp.to/proto/maildir.html for flag conventions.
+
+  message.add_flag("S") # Mark the message as "seen"
+  message.add_flag("F") # Mark the message as "flagged"
+  message.remove_flag("F") # unflag the message
+  message.add_flag("T") # Mark the message as "trashed"
+
+Get a key to uniquely identify the message
+
+  key = message.key
+
+Load the contents of the message
+
+  data = message.data
+
+Find the message based using the key
+
+  message_copy = maildir.get(key)
+  message == message_copy # => true
+
+Delete the message from disk
+
+  message.destroy # => returns the frozen message
+  maildir.list(:cur) # => []
+
+== Pluggable serializers
+
+By default, message data are written and read from disk as a string. It's often desirable to process the string into a useful object. Maildir supports configurable serializers to convert message data into a useful object.
+
+The following serializers are included:
+
+* Maildir::Serializer::Base (the default)
+* Maildir::Serializer::Mail
+* Maildir::Serializer::Marshal
+* Maildir::Serializer::JSON
+* Maildir::Serializer::YAML
+
+Maildir::Serializer::Base simply reads and writes strings to disk.
+
+  Maildir::Message.serializer # => Maildir::Serializer::Base.new (by default)
+  message = maildir.add("Hello World!") # writes "Hello World!" to disk
+  message.data # => "Hello World!"
+
+The Mail serializer takes a ruby Mail object (http://github.com/mikel/mail) and writes RFC2822 email messages.
+
+  Maildir::Message.serializer = Maildir::Serializer::Mail.new
+  mail = Mail.new(...)
+  message = maildir.add(mail) # writes and RFC2822 message to disk
+  message.data == mail # => true; data is parsed as a Mail object
+
+The Marshal, JSON, and YAML serializers work similarly. E.g.
+
+  Maildir::Message.serializer = Maildir::Serializer::JSON.new
+  my_data = {"foo" => nil, "my_array" => [1,2,3]}
+  message = maildir.add(my_data) # writes {"foo":null,"my_array":[1,2,3]}
+  message.data == my_data # => true
+
+It's trivial to create a custom serializer. Implement the following two methods:
+
+  load(path)
+  dump(data, path)
 
 == Copyright
 
-Copyright (c) 2009 Aaron Suggs. See LICENSE for details.
+Copyright (c) 2010 Aaron Suggs. See LICENSE for details.

data/Rakefile

@@ -16,7 +16,9 @@ begin
     gemspec.email = "aaron@ktheory.com"
     gemspec.homepage = "http://github.com/ktheory/maildir"
     gemspec.authors = ["Aaron Suggs"]
-    gemspec.add_development_dependency "thoughtbot-shoulda", ">= 0"
+    gemspec.add_development_dependency "shoulda", ">= 0"
+    gemspec.add_development_dependency "mail", ">= 0"
+    gemspec.add_development_dependency "json", ">= 0"
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/benchmarks/runner

@@ -9,7 +9,7 @@ maildir = Maildir.new(maildir_path)
 n = 300
 message = "Write #{n} messages:"
 tms = Benchmark.bmbm(message.size) do |x|
-   x.report(message) { n.times { maildir.add_message("") } }
+   x.report(message) { n.times { maildir.add("") } }
 end
 
 puts "#{n/tms.first.real} messages per second"

data/lib/maildir/message.rb

@@ -4,19 +4,28 @@ class Maildir::Message
   # The default info, to which flags are appended
   INFO = "2,"
 
+  include Comparable
+
   class << self
-    # Create a new message in maildir with the contents of string_or_io.
+    # Create a new message in maildir with data.
     # The message is first written to the tmp dir, then moved to new. This is
     # a shortcut for:
     #   message = Maildir::Message.new(maildir)
-    #   message.write(string_or_io)
-    def create(maildir, string_or_io)
+    #   message.write(data)
+    def create(maildir, data)
       message = self.new(maildir)
-      message.write(string_or_io)
+      message.write(data)
       message
     end
+
+    # The serializer processes data before it is written to disk and after
+    # reading from disk.
+    attr_accessor :serializer
   end
 
+  # Default serializer
+  @serializer = Maildir::Serializer::Base.new
+
   attr_reader :dir, :unique_name, :info, :old_key
 
   # Create a new, unwritten message or instantiate an existing message.
@@ -43,24 +52,32 @@ class Maildir::Message
     end
   end
 
-  # Writes string_or_io to disk. Can only be called on messages
-  # instantiated without a key (which haven't been written to disk). If the
-  # +string_or_io+ object has a 'read' method, calls string_or_io.read.
-  # Otherwise, calls string_or_io.to_s.
+  # Compares messages by their paths.
+  # If message is a different class, return nil.
+  # Otherwise, return 1, 0, or -1.
+  def <=>(message)
+    # Return nil if comparing different classes
+    return nil unless self.class === message
+
+    self.path <=> message.path
+  end
+
+  # Returns the class' serializer
+  def serializer
+    self.class.serializer
+  end
+
+  # Writes data to disk. Can only be called on messages instantiated without
+  # a key (which haven't been written to disk). After successfully writing
+  # to disk, rename the message to the new dir
   #
   # Returns the message's key
-  def write(string_or_io)
+  def write(data)
     raise "Can only write to messages in tmp" unless :tmp == @dir
+
     # Write out contents to tmp
-    File.open(path, 'w') do |file|
-      if string_or_io.respond_to?(:read)
-        file.puts string_or_io.read
-      else
-        file.puts string_or_io.to_s
-      end
-    end
+    serializer.dump(data, path)
 
-    # Rename to new
     rename(:new)
   end
 
@@ -112,6 +129,11 @@ class Maildir::Message
     File.join(@maildir.path, key)
   end
 
+  # Returns the message's data from disk
+  def data
+    serializer.load(path)
+  end
+
   # Deletes the message path and freezes the message object
   def destroy
     File.delete(path)
@@ -119,6 +141,7 @@ class Maildir::Message
   end
 
   protected
+
   # Sets dir, unique_name, and info based on the key
   def parse_key(key)
     @dir, filename = key.split(File::SEPARATOR)

data/lib/maildir/serializer/base.rb

@@ -0,0 +1,20 @@
+module Maildir::Serializer
+  # The Maildir::Serializer::Base class reads & writes data to disk as a
+  # string. Other serializers (e.g. Maildir::Serializer::Mail) can extend this
+  # class to do some pre- and post-processing of the string.
+  #
+  # The Serializer API has two methods:
+  #   load(path) # => returns data
+  #   dump(data, path) # => returns number of bytes written
+  class Base
+    # Reads the file at path. Returns the contents of path.
+    def load(path)
+      File.read(path)
+    end
+
+    # Writes data to path. Returns number of bytes written.
+    def dump(data, path)
+      File.open(path, "w") {|file| file.write(data)}
+    end
+  end
+end

data/lib/maildir/serializer/json.rb

@@ -0,0 +1,13 @@
+require 'json'
+# Serialize messages as JSON
+class Maildir::Serializer::JSON < Maildir::Serializer::Base
+  # Read data from path and parse it as JSON.
+  def load(path)
+    ::JSON.load(super(path))
+  end
+
+  # Dump data as JSON and writes it to path.
+  def dump(data, path)
+    super(data.to_json, path)
+  end
+end

data/lib/maildir/serializer/mail.rb

@@ -0,0 +1,13 @@
+require 'mail'
+# Serialize messages as a ruby Mail object
+class Maildir::Serializer::Mail < Maildir::Serializer::Base
+  # Build a new Mail object from the data at path.
+  def load(path)
+    ::Mail.new(super(path))
+  end
+  
+  # Write data to path as a Mail message.
+  def dump(data, path)
+    super(data.to_s, path)
+  end
+end

data/lib/maildir/serializer/marshal.rb

@@ -0,0 +1,12 @@
+# Serialize messages as Marshalled ruby objects
+class Maildir::Serializer::Marshal < Maildir::Serializer::Base
+  # Read data from path and unmarshal it.
+  def load(path)
+    ::Marshal.load(super(path))
+  end
+
+  # Marshal data and write it to path.
+  def dump(data, path)
+    super(::Marshal.dump(data), path)
+  end
+end

data/lib/maildir/serializer/yaml.rb

@@ -0,0 +1,13 @@
+require 'yaml'
+# Serialize messages as YAML
+class Maildir::Serializer::YAML < Maildir::Serializer::Base
+  # Read data from path and parse it as YAML.
+  def load(path)
+    ::YAML.load(super(path))
+  end
+
+  # Dump data as YAML and writes it to path.
+  def dump(data, path)
+    super(data.to_yaml, path)
+  end
+end

data/lib/maildir.rb

@@ -1,19 +1,28 @@
-require 'fileutils'
+require 'fileutils' # For create_directories
 class Maildir
 
   SUBDIRS = [:tmp, :new, :cur].freeze
   READABLE_DIRS = SUBDIRS.reject{|s| :tmp == s}.freeze
 
+  include Comparable
+
   attr_reader :path
+
+  # Create a new maildir at +path+. If +create+ is true, will ensure that the
+  # required subdirectories exist.
   def initialize(path, create = true)
     @path = File.join(path, '/') # Ensure path has a trailing slash
-    create_subdirectories if create
+    create_directories if create
   end
 
-  # Maildirs are indentical if they have the same path
-  def ==(maildir)
-    return false unless Maildir === maildir
-    maildir.path == self.path
+  # Compare maildirs by their paths.
+  # If maildir is a different class, return nil.
+  # Otherwise, return 1, 0, or -1.
+  def <=>(maildir)
+    # Return nil if comparing different classes
+    return nil unless self.class === maildir
+
+    self.path <=> maildir.path
   end
 
   # define methods tmp_path, new_path, & cur_path
@@ -26,31 +35,47 @@ class Maildir
   # Ensure subdirectories exist. This can safely be called multiple times, but
   # must hit the disk. Avoid calling this if you're certain the directories
   # exist.
-  def create_subdirectories
+  def create_directories
     SUBDIRS.each do |subdir|
       FileUtils.mkdir_p(self.send("#{subdir}_path"))
     end
   end
 
-  def list(new_or_cur)
-    list_keys(new_or_cur).map{|key| get_message(key)}
-  end
-
-  def list_keys(new_or_cur)
+  # Returns an arry of messages from :new or :cur directory, sorted by key.
+  # If options[:limit] is specified, returns only so many keys.
+  #
+  # E.g.
+  #  maildir.list(:new) # => all new messages
+  #  maildir.list(:cur, :limit => 10) # => 10 oldest messages in cur
+  def list(new_or_cur, options = {})
     new_or_cur = new_or_cur.to_sym
     unless [:new, :cur].include? new_or_cur
       raise ArgumentError, "first arg must be new or cur"
     end
-    get_dir_listing(new_or_cur)
+
+    keys = get_dir_listing(new_or_cur)
+
+    # Map keys to message objects
+    messages = keys.map{|key| get(key)}
+
+    # Sort the messages (effectively chronological order)
+    # TODO: make sorting configurable
+    messages.sort!
+
+    # Apply the limit
+    if limit = options[:limit]
+      messages = messages[0,limit]
+    end
+    messages
   end
 
-  # Writes string_or_io object out as a new message. See
+  # Writes data object out as a new message. Returns a Maildir::Message. See
   # Maildir::Message.create for more.
-  def add_message(string_or_io)
-    Maildir::Message.create(self, string_or_io)
+  def add(data)
+    Maildir::Message.create(self, data)
   end
 
-  def get_message(key)
+  def get(key)
     Maildir::Message.new(self, key)
   end
 
@@ -66,6 +91,6 @@ class Maildir
     end
   end
 end
-
 require 'maildir/unique_name'
+require 'maildir/serializer/base'
 require 'maildir/message'

data/maildir.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{maildir}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Aaron Suggs"]
-  s.date = %q{2010-01-05}
+  s.date = %q{2010-01-08}
   s.description = %q{A ruby library for reading and writing arbitrary messages in DJB's maildir format}
   s.email = %q{aaron@ktheory.com}
   s.extra_rdoc_files = [
@@ -19,18 +19,23 @@ Gem::Specification.new do |s|
   s.files = [
     ".gitignore",
      "LICENSE",
-     "NOTES.txt",
      "README.rdoc",
      "Rakefile",
      "VERSION",
      "benchmarks/runner",
      "lib/maildir.rb",
      "lib/maildir/message.rb",
+     "lib/maildir/serializer/base.rb",
+     "lib/maildir/serializer/json.rb",
+     "lib/maildir/serializer/mail.rb",
+     "lib/maildir/serializer/marshal.rb",
+     "lib/maildir/serializer/yaml.rb",
      "lib/maildir/unique_name.rb",
      "maildir.gemspec",
      "test/test_helper.rb",
      "test/test_maildir.rb",
      "test/test_message.rb",
+     "test/test_serializers.rb",
      "test/test_unique_name.rb"
   ]
   s.homepage = %q{http://github.com/ktheory/maildir}
@@ -42,6 +47,7 @@ Gem::Specification.new do |s|
     "test/test_helper.rb",
      "test/test_maildir.rb",
      "test/test_message.rb",
+     "test/test_serializers.rb",
      "test/test_unique_name.rb"
   ]
 
@@ -50,12 +56,18 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<mail>, [">= 0"])
+      s.add_development_dependency(%q<json>, [">= 0"])
     else
-      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<mail>, [">= 0"])
+      s.add_dependency(%q<json>, [">= 0"])
     end
   else
-    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<mail>, [">= 0"])
+    s.add_dependency(%q<json>, [">= 0"])
   end
 end
 

data/test/test_maildir.rb

@@ -2,11 +2,6 @@ require 'test_helper'
 class TestMaildir < Test::Unit::TestCase
 
   context "A maildir" do
-
-    should "be initialized" do
-      assert temp_maildir
-    end
-
     should "have a path" do
       assert_not_empty temp_maildir.path
     end
@@ -36,14 +31,21 @@ class TestMaildir < Test::Unit::TestCase
     
     context "with a message" do
       setup do
-        @key = temp_maildir.add_message("").key
+        @message = temp_maildir.add("")
       end
 
       should "list the message in it's keys" do
-        keys = temp_maildir.list_keys(:new)
-        assert_equal keys, [@key]
+        messages = temp_maildir.list(:new)
+        assert_equal messages, [@message]
       end
     end
   end
 
+  context "Maildirs with the same path" do
+    should "be identical" do
+      another_maildir = Maildir.new(temp_maildir.path, false)
+      assert_equal temp_maildir, another_maildir
+    end
+  end
+
 end

data/test/test_message.rb

@@ -1,7 +1,6 @@
 require 'test_helper'
 class TestMessage < Test::Unit::TestCase
 
-
   context "An new, unwritten message" do
     setup do
       @message = Maildir::Message.new(temp_maildir)
@@ -66,18 +65,7 @@ class TestMessage < Test::Unit::TestCase
       end
 
       should "have the correct data" do
-        assert @data == File.open(@message.path).read
-      end
-    end
-
-    context "when written with an IO object" do
-      setup do
-        @data = "foo\n"
-        @message.write(StringIO.open(@data))
-      end
-
-      should "have the correct data" do
-        assert @data == File.open(@message.path).read
+        assert_equal @data, @message.data
       end
     end
   end
@@ -89,7 +77,7 @@ class TestMessage < Test::Unit::TestCase
     end
 
     should "have the correct data" do
-      assert @data == File.open(@message.path).read
+      assert_equal @data, @message.data
     end
 
     context "when processed" do
@@ -158,4 +146,24 @@ class TestMessage < Test::Unit::TestCase
       end
     end
   end
+
+  context "Messages" do
+    setup do
+      @message1 = temp_maildir.add("")
+    end
+    
+    should "differ" do
+      @message2 = Maildir::Message.new(temp_maildir)
+      assert_equal -1, @message1 <=> @message2
+      assert_equal 1,  @message2 <=> @message1
+      assert_not_equal @message1, @message2
+      
+    end
+    
+    should "be identical" do
+      another_message1 = temp_maildir.get(@message1.key)
+      assert_equal @message1, another_message1
+    end
+  end
+
 end

data/test/test_serializers.rb

@@ -0,0 +1,43 @@
+require 'test_helper'
+
+# Require all the serializers
+path = File.join(File.dirname(__FILE__), "..","lib","maildir","serializer","*")
+Dir.glob(path).each do |file|
+  require file
+end
+
+class TestSerializers < Test::Unit::TestCase
+
+  serializers = [
+    [Maildir::Serializer::Mail,    lambda {|data| Mail.new(data).to_s}],
+    [Maildir::Serializer::Marshal, lambda {|data| Marshal.dump(data)}],
+    [Maildir::Serializer::JSON,    lambda {|data| JSON.dump(data)}],
+    [Maildir::Serializer::YAML,    lambda {|data| YAML.dump(data)}]
+  ]
+
+  serializers.each do |klass, dumper|
+    context "A message serialized with #{klass}" do
+      setup do
+        @data = case klass.new
+        when Maildir::Serializer::Mail
+          Mail.new
+        else
+          # Test a few common data structures
+          [1, nil, {"foo" => true}]
+        end
+
+        # Set the message serializer
+        Maildir::Message.serializer = klass.new
+        @message = temp_maildir.add(@data)
+      end
+
+      should "have the correct data" do
+        assert_equal @data, @message.data
+      end
+
+      should "have serialized data on disk" do
+        assert_equal dumper.call(@data), File.read(@message.path)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: maildir
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Aaron Suggs
@@ -9,11 +9,31 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-05 00:00:00 -05:00
+date: 2010-01-08 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: thoughtbot-shoulda
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mail
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: json
   type: :development
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
@@ -34,18 +54,23 @@ extra_rdoc_files:
 files: 
 - .gitignore
 - LICENSE
-- NOTES.txt
 - README.rdoc
 - Rakefile
 - VERSION
 - benchmarks/runner
 - lib/maildir.rb
 - lib/maildir/message.rb
+- lib/maildir/serializer/base.rb
+- lib/maildir/serializer/json.rb
+- lib/maildir/serializer/mail.rb
+- lib/maildir/serializer/marshal.rb
+- lib/maildir/serializer/yaml.rb
 - lib/maildir/unique_name.rb
 - maildir.gemspec
 - test/test_helper.rb
 - test/test_maildir.rb
 - test/test_message.rb
+- test/test_serializers.rb
 - test/test_unique_name.rb
 has_rdoc: true
 homepage: http://github.com/ktheory/maildir
@@ -79,4 +104,5 @@ test_files:
 - test/test_helper.rb
 - test/test_maildir.rb
 - test/test_message.rb
+- test/test_serializers.rb
 - test/test_unique_name.rb

data/NOTES.txt

@@ -1,17 +0,0 @@
-md = Maildir.new(path)
-
-md.add(data) => message
-
-md.list_new => array of messages
-
-md.list_cur => array of messages
-
-message.process(flags) => moves message from new to cur and adds flags
-
-message.flags
-message.flags=
-message.add_flag
-message.remove_flag
-
-message.info
-message.info=