maildir 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Aaron Suggs
+
+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/NOTES.txt

@@ -0,0 +1,17 @@
+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=

data/README.rdoc

@@ -0,0 +1,9 @@
+= Maildir
+
+A ruby library for reading and writing messages in the maildir format.
+
+See http://cr.yp.to/proto/maildir.html
+
+== Copyright
+
+Copyright (c) 2009 Aaron Suggs. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,24 @@
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
+task :default => :test
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "maildir"
+    gemspec.summary = "Read & write messages in the maildir format"
+    gemspec.description = "A ruby library for reading and writing arbitrary messages in DJB's maildir format"
+    gemspec.email = "aaron@ktheory.com"
+    gemspec.homepage = "http://github.com/ktheory/maildir"
+    gemspec.authors = ["Aaron Suggs"]
+    gemspec.add_development_dependency "thoughtbot-shoulda", ">= 0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/benchmarks/runner

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'maildir'

data/lib/maildir.rb

@@ -0,0 +1,66 @@
+class Maildir
+
+  SUBDIRS = [:tmp, :new, :cur].freeze
+  READABLE_DIRS = SUBDIRS.reject{|s| :tmp == s}.freeze
+
+  attr_reader :path
+  def initialize(path, create = true)
+    @path = File.join(path, '/') # Ensure path has a trailing slash
+    create_subdirectories if create
+  end
+
+  # Maildirs are indentical if they have the same path
+  def ==(maildir)
+    return false unless Maildir === maildir
+    maildir.path == self.path
+  end
+
+  # define methods tmp_path, new_path, & cur_path
+  SUBDIRS.each do |subdir|
+    define_method "#{subdir}_path" do
+      File.join(path, subdir.to_s)
+    end
+  end
+
+  # 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
+    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)
+    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)
+  end
+
+  # Writes IO object out as a new message. See Maildir::Message.create for
+  # more.
+  def add_message(io)
+    Maildir::Message.create(self, io)
+  end
+
+  def get_message(key)
+    Maildir::Message.new(self, key)
+  end
+
+  protected
+  def get_dir_listing(new_or_cur)
+    search_path = File.join(self.path, new_or_cur.to_s, '*')
+    results = Dir.glob(search_path)
+    # Remove the maildir's path from the beginning of the message path
+    results.map!{|message_path| message_path.sub!(self.path, '')}
+  end
+end
+
+require 'maildir/unique_name'
+require 'maildir/message'

data/lib/maildir/message.rb

@@ -0,0 +1,131 @@
+class Maildir::Message
+  # COLON seperates the unique name from the info
+  COLON = ':'
+  # The default info, to which flags are appended
+  INFO = "2,"
+
+  class << self
+    # Create a new message in maildir with the contents of io. 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(io)
+    def create(maildir, io)
+      message = self.new(maildir)
+      message.write(io)
+      message
+    end
+  end
+
+  attr_reader :dir, :unique_name, :info, :old_key
+
+  # Create a new, unwritten message:
+  # Message.new(maildir)
+  #
+  # Instantiate an existing message:
+  # Message.new(maildir, key)
+  def initialize(maildir, key=nil)
+    @maildir = maildir
+    if key.nil?
+      @dir = :tmp
+    else
+      parse_key(key)
+    end
+
+    raise ArgumentError, "State must be in #{Maildir::SUBDIRS.inspect}" unless Maildir::SUBDIRS.include? dir
+
+    if :tmp == dir
+      @unique_name = Maildir::UniqueName.create
+    end
+  end
+
+  # Writes io to disk. Can only be called on messages instantiated without a
+  # key (which haven't been written to disk). If the io object has a 'read'
+  # method, calls io.read. Otherwise, calls io.to_s.
+  def write(io)
+    raise "Can only write to messages in tmp" unless :tmp == @dir
+    # Write out contents to tmp
+    File.open(path, 'w') do |file|
+      file.puts io.respond_to?(:read) ? io.read : io.to_s
+    end
+
+    # Rename to new
+    rename(:new)
+
+  end
+
+  # Move a message from new to cur, add info
+  def process
+    rename(:cur, INFO)
+  end
+
+  def info=(info)
+    raise "Can only set info on cur messages" unless :cur == @dir
+    rename(:cur, info)
+  end
+
+  # Returns an array of single letter flags applied to the message
+  def flags
+    @info.sub(INFO,'').split('')
+  end
+
+  def flags=(*flags)
+    self.info = INFO + sort_flags(flags.flatten.join(''))
+  end
+
+  def add_flag(flag)
+    self.flags = (flags << flag.upcase)
+  end
+  
+  def remove_flag(flag)
+    self.flags = flags.delete_if{|f| f == flag.upcase}
+  end
+
+
+  # Returns the filename of the message
+  def filename
+    [unique_name, info].compact.join(COLON)
+  end
+
+  # Returns the key to identify the message
+  def key
+    File.join(dir.to_s, filename)
+  end
+
+  # Returns the full path to the message
+  def path
+    File.join(@maildir.path, key)
+  end
+
+  def old_path
+    File.join(@maildir.path, old_key)
+  end
+
+  protected
+  # Sets dir, unique_name, and info based in key
+  def parse_key(key)
+    @dir, filename = key.split(File::SEPARATOR)
+    @dir = @dir.to_sym
+    @unique_name, @info = filename.split(COLON)
+  end
+
+  def sort_flags(flags)
+    flags.split('').map{|f| f.upcase}.sort!.uniq.join('')
+  end
+
+  def rename(new_dir, new_info=nil)
+    # Safe the old key so we can revert to the old state
+    @old_key = key
+
+    # Set the new state
+    @dir = new_dir
+    @info = new_info if new_info
+
+    begin
+      File.rename(old_path, path) unless old_path == path
+    rescue Errno::ENOENT
+      # Restore ourselves to the old state
+      parse_key(@old_key)
+      raise
+    end
+  end
+end

data/lib/maildir/unique_name.rb

@@ -0,0 +1,72 @@
+# Class for generating unique file names for new messages
+class Maildir::UniqueName
+  require 'thread' # For mutex support
+  require 'socket' # For getting the hostname
+  class << self
+    # Return a thread-safe increasing counter
+    def counter
+      @counter_mutex ||= Mutex.new
+      @counter_mutex.synchronize do
+        @counter = @counter.to_i + 1
+      end
+    end
+
+    def create
+      self.new.to_s
+    end
+  end
+
+  # Return a unique file name based on strategy
+  def initialize
+    # Use the same time object
+    @now = Time.now
+  end
+
+  # Return the name as a string
+  def to_s
+    [left, middle, right].join(".")
+  end
+
+  protected
+  # The left part of the unique name is the number of seconds from since the
+  # UNIX epoch
+  def left
+    @now.to_i.to_s
+  end
+
+  # The middle part contains the microsecond, the process id, and a
+  # per-process incrementing counter
+  def middle
+    "M#{microsecond}P#{process_id}Q#{delivery_count}"
+  end
+
+  # The right part is the hostname
+  def right
+    Socket.gethostname
+  end
+
+  def secure_random(bytes=8)
+    # File.read("/dev/urandom", bytes).unpack("H*")[0]
+    raise "Not implemented"
+  end
+
+  def inode
+    raise "Not implemented"
+  end
+
+  def device_number
+    raise "Not implemented"
+  end
+
+  def microsecond
+    @now.usec.to_s
+  end
+
+  def process_id
+    Process.pid.to_s
+  end
+
+  def delivery_count
+    self.class.counter.to_s
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,24 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'tmpdir'
+require 'tempfile'
+require 'fileutils'
+require 'maildir'
+
+# Create a reusable maildir that's cleaned up when the tests are done
+def temp_maildir
+  return $maildir if $maildir
+  
+  dir_path = Dir.mktmpdir("maildir_test")
+  at_exit do
+    puts "Cleaning up temp maildir"
+    FileUtils.rm_r(dir_path)
+  end
+  $maildir = Maildir.new(dir_path)
+end
+
+# Useful for testing that strings defined & not empty
+def assert_not_empty(obj, msg='')
+  assert !obj.nil? && !obj.empty?, msg
+end

data/test/test_maildir.rb

@@ -0,0 +1,38 @@
+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
+
+    should "create subdirectories by default" do
+      %w(tmp new cur).each do |subdir|
+        subdir_path = temp_maildir.send("#{subdir}_path")
+        assert File.directory?(subdir_path), "Subdir #{subdir} does not exist"
+      end
+    end
+
+    should "not create directories if specified" do
+      tmp_dir = Dir.mktmpdir('new_maildir_test')
+      maildir = Maildir.new(tmp_dir, false)
+      %w(tmp new cur).each do |subdir|
+        subdir_path = maildir.send("#{subdir}_path")
+        assert !File.directory?(subdir_path), "Subdir #{subdir} exists"
+      end
+      FileUtils.rm_r(tmp_dir)
+    end
+    
+    should "be identical to maildirs with the same path" do
+      new_maildir = Maildir.new(temp_maildir.path)
+      assert_equal temp_maildir.path, new_maildir.path
+      assert_equal temp_maildir, new_maildir
+    end
+  end
+
+end

data/test/test_message.rb

@@ -0,0 +1,152 @@
+require 'test_helper'
+class TestMessage < Test::Unit::TestCase
+
+
+  context "An new, unwritten message" do
+    setup do
+      @message = Maildir::Message.new(temp_maildir)
+    end
+
+    should "be instantiated" do
+      assert @message
+    end
+
+    should "be in :tmp" do
+      assert_equal :tmp, @message.dir
+      assert_match(/tmp/, @message.path)
+    end
+
+    should "have a unique name" do
+      assert_not_empty @message.unique_name
+    end
+
+    should "have a file name" do
+      assert_not_empty @message.filename
+    end
+
+    should "have no info" do
+      assert_nil @message.info
+    end
+
+    should "not be able to set info" do
+      assert_raises RuntimeError do
+        @message.info= "2,FRS"
+      end
+    end
+
+    context "when written with a string" do
+      setup do
+        @data = "foo\n"
+        @message.write(@data)
+      end
+
+      should "not be writable" do
+        assert_raise RuntimeError do
+          @message.write("nope!")
+        end
+      end
+
+      should "have no info" do
+        assert_nil @message.info
+      end
+
+      should "not be able to set info" do
+        assert_raises RuntimeError do
+          @message.info= "2,FRS"
+        end
+      end
+
+      should "be in new dir" do
+        assert_equal :new, @message.dir
+        assert_match(/new/, @message.path)
+      end
+
+      should "have have a file" do
+        assert File.exists?(@message.path)
+      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
+      end
+    end
+  end
+
+  context "A created message" do
+    setup do
+      @data = "foo\n"
+      @message = Maildir::Message.create(temp_maildir, @data)
+    end
+
+    should "have the correct data" do
+      assert @data == File.open(@message.path).read
+    end
+
+    context "when processed" do
+      setup do
+        @message.process
+      end
+
+      should "not be writable" do
+        assert_raise RuntimeError do
+          @message.write("nope!")
+        end
+      end
+
+      should "be in cur" do
+        assert_equal :cur, @message.dir
+      end
+
+      should "have info" do
+        assert_equal Maildir::Message::INFO, @message.info
+      end
+
+      should "set info" do
+        info = "2,FRS"
+        @message.info = "2,FRS"
+        assert_equal @message.info, info
+        assert_match /#{info}$/, @message.path
+      end
+
+      should "add and remove flags" do
+        @message.add_flag('S')
+        assert_equal ['S'], @message.flags
+
+        # Test lowercase
+        @message.add_flag('r')
+        assert_equal ['R', 'S'], @message.flags
+
+        @message.remove_flag('S')
+        assert_equal ['R'], @message.flags
+
+        # Test lowercase
+        @message.remove_flag('r')
+        assert_equal [], @message.flags
+      end
+
+      flag_tests = {
+        "FRS" => ['F', 'R', 'S'],
+        "Sr" => ['R', 'S'], # test capitalization & sorting
+        '' => []
+      }
+      flag_tests.each do |arg, results|
+        should "set flags: #{arg}" do
+          @message.flags = arg
+          assert_equal results, @message.flags
+          path_suffix = "#{Maildir::Message::INFO}#{results.join('')}"
+          assert_match /#{path_suffix}$/, @message.path
+        end
+      end
+    end
+  end
+end

data/test/test_unique_name.rb

@@ -0,0 +1,43 @@
+require 'test_helper'
+class TestUniqueName < Test::Unit::TestCase
+
+  context "A UniqueName" do
+    setup do
+      @raw_name = Maildir::UniqueName.new
+      @name = @raw_name.to_s
+      @now = @raw_name.send(:instance_variable_get, :@now)
+    end
+
+    should "be initialized" do
+      assert @raw_name
+    end
+
+    should "have a name" do
+      assert_not_empty @name
+    end
+
+    should "begin with timestamp" do
+      assert_match /^#{@now.to_i}/, @name
+    end
+
+    should "end with hostname" do
+      assert_match /#{Socket.gethostname}$/, @name
+    end
+
+    should "be unique when created in the same microsecond" do
+      @new_name = Maildir::UniqueName.new
+      # Set @now be identical in both UniqueName instances
+      @new_name.send(:instance_variable_set, :@now, @now)
+      assert_not_equal @name, @new_name.to_s
+    end
+
+  end
+
+  context "The UniqueName counter" do
+    should "increment when called" do
+      value1 = Maildir::UniqueName.counter
+      value2 = Maildir::UniqueName.counter
+      assert_equal value1+1, value2
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: maildir
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Aaron Suggs
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-05 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A ruby library for reading and writing arbitrary messages in DJB's maildir format
+email: aaron@ktheory.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- NOTES.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- benchmarks/runner
+- lib/maildir.rb
+- lib/maildir/message.rb
+- lib/maildir/unique_name.rb
+- test/test_helper.rb
+- test/test_maildir.rb
+- test/test_message.rb
+- test/test_unique_name.rb
+has_rdoc: true
+homepage: http://github.com/ktheory/maildir
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Read & write messages in the maildir format
+test_files: 
+- test/test_helper.rb
+- test/test_maildir.rb
+- test/test_message.rb
+- test/test_unique_name.rb