rmail 0.17

data/lib/rmail/mailbox.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+#--
+#   Copyright (c) 2002, 2003 Matt Armstrong.  All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+# NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+#++
+# Implements the RMail::Mailbox module.
+
+module RMail
+
+  # The RMail::Mailbox module contains a few methods that are useful
+  # for working with mailboxes.
+  module Mailbox
+
+    class << self
+
+      # Parse a Unix mbox style mailbox.  These mailboxes searate
+      # individual messages with a line beginning with the string
+      # "From ".
+      #
+      # If a block is given, yields to the block with the raw message
+      # (a string), otherwise an array of raw message strings is
+      # returned.
+      def parse_mbox(input, line_separator = $/)
+        require 'rmail/mailbox/mboxreader'
+        retval = []
+        RMail::Mailbox::MBoxReader.new(input, line_separator).each_message {
+          |reader|
+          raw_message = reader.read(nil)
+          if block_given?
+            yield raw_message
+          else
+            retval << raw_message
+          end
+        }
+        return block_given? ? nil : retval
+      end
+
+    end
+  end
+end

data/lib/rmail/mailbox/mboxreader.rb

@@ -0,0 +1,182 @@
+#--
+#   Copyright (c) 2002, 2003 Matt Armstrong.  All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+# NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+#++
+# Implements the RMail::Mailbox::MBoxReader class.
+
+require 'rmail/parser/pushbackreader'
+
+module RMail
+  module Mailbox
+
+    # Class that can parse Unix mbox style mailboxes.  These mailboxes
+    # separate individual messages with a line beginning with the
+    # string "From ".
+    #
+    # Typical usage:
+    #
+    #  File.open("file.mbox") { |file|
+    #    RMail::Mailbox::MBoxReader.new(file).each_message { |input|
+    #      message = RMail::Parser.read(input)
+    #      # do something with the message
+    #    end
+    #  }
+    #
+    # Or see RMail::Mailbox.parse_mbox for a more convenient
+    # interface.
+    #
+    class MBoxReader < RMail::Parser::PushbackReader
+
+      # Creates a new MBoxReader that reads from `input' with lines
+      # that end with `line_separator'.
+      #
+      # `input' can either be an IO source (an object that responds to
+      # the "read" method in the same way as a standard IO object) or
+      # a String.
+      #
+      # `line_separator' defaults to $/, and useful values are
+      # probably limited to "\n" (Unix) and "\r\n" (DOS/Windows).
+      def initialize(input, line_separator = $/)
+        super(input)
+        @end_of_message = false
+        @chunk_minsize = 0
+        @sep = line_separator
+        @tail = nil
+
+        # This regexp will match a From_ header, or some prefix.
+        re_string = RMail::Parser::PushbackReader.
+          maybe_contains_re("#{@sep}From ")
+        @partial_from_re = Regexp.new(re_string)
+
+        # This regexp will match an entire From_ header.
+        @entire_from_re = /\A#{@sep}From .*?#{@sep}/
+      end
+
+      alias_method :parent_read_chunk, :read_chunk
+
+      # Reads some data from the current message and returns it.  The
+      # `size' argument is just a suggestion, and the returned string
+      # can be larger or smaller.  When `size' is nil, then the entire
+      # message is returned.
+      #
+      # Once all data from the current message has been read, #read
+      # returns nil and #next must be called to begin reading from the
+      # next message.  You can use #eof to tell if there is any more
+      # data to be read from the input source.
+      def read_chunk(size)
+        chunk = read_chunk_low(size)
+        if chunk
+          if chunk.length > @sep.length
+            @tail = chunk[-@sep.length .. -1]
+          else
+            @tail ||= ''
+            @tail << chunk
+          end
+        elsif @tail
+          if @tail[-@sep.length .. -1] != @sep
+            chunk = @sep
+          end
+          @tail = nil
+        end
+        chunk
+      end
+
+      # Advances to the next message to be read.  Call this after
+      # #read returns nil.
+      #
+      # Note: Once #read returns nil, you can call #eof before or
+      # after calling #next to tell if there actually is a next
+      # message to read.
+      def next
+        @end_of_message = false
+        @tail = nil
+      end
+
+      alias_method :parent_eof, :eof
+
+      # Returns true if the next call to read_chunk will return nil.
+      def eof
+        parent_eof and @tail.nil?
+      end
+
+      # Yield self until eof, calling next after each yield.
+      #
+      # This method makes it simple to read messages successively out
+      # of the mailbox.  See the class description for a code example.
+      def each_message
+        while !eof
+          yield self
+          self.next
+        end
+      end
+
+      private
+
+      def read_chunk_low(size)
+        return nil if @end_of_message
+        if chunk = parent_read_chunk(size)
+          # Read at least @chunk_minsize bytes.
+          while chunk.length < @chunk_minsize && more = parent_read_chunk(size)
+            chunk << more
+          end
+          if match = @partial_from_re.match(chunk)
+            # We matched what might be a From_ separator.  Separate
+            # the chunk into what came before and what came after it.
+            mbegin = match.begin(0)
+            rest = chunk[mbegin .. -1]
+
+            if @entire_from_re =~ rest
+              # We've got a full From_ line, so set the end of message
+              # flag and get rid of the line separator present just
+              # before the From_.
+              @end_of_message = true
+              @chunk_minsize = 0
+              rest[0, @sep.length] = "" # painful
+            else
+              # Make sure that next time we read more than just the
+              # pushback.
+              @chunk_minsize = rest.length + 1
+            end
+
+            # Return the whole chunk with a partially matched From_
+            # when there is nothing further to read.
+            unless ! @end_of_message && parent_eof
+              # Otherwise, push back the From_ and return the
+              # pre-match.
+              pushback(rest)
+              if mbegin == 0 and @end_of_message
+                chunk = nil
+              else
+                chunk = chunk[0, mbegin]
+              end
+            end
+
+          end
+        end
+        return chunk
+      end
+    end
+  end
+end

data/lib/rmail/message.rb

@@ -0,0 +1,201 @@
+#--
+#   Copyright (C) 2001, 2002, 2003 Matt Armstrong.  All rights
+#   reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+# NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+#++
+# Implements the RMail::Message class.
+
+require 'rmail/header.rb'
+
+module RMail
+
+  # The RMail::Message is an object representation of a standard
+  # Internet email message, including MIME multipart messages.
+  #
+  # An RMail::Message object represents a message header (held in the
+  # contained RMail::Header object) and a message body.  The message
+  # body may either be a single String for single part messages or an
+  # Array of RMail::Message objects for MIME multipart messages.
+  class Message
+
+    # Create a new, empty, RMail::Message.
+    def initialize
+      @header = RMail::Header.new
+      @body = nil
+      @epilogue = nil
+      @preamble = nil
+    end
+
+    # Test if this message is structured exactly the same as the other
+    # message.  This is useful mainly for testing.
+    def ==(other)
+      @preamble == other.preamble &&
+        @epilogue == other.epilogue &&
+        @header == other.header &&
+        @body == other.body
+    end
+
+    # Returns the body of the message as a String or Array.
+    #
+    # If #multipart? returns true, it will be an array of
+    # RMail::Message objects.  Otherwise it will be a String.
+    #
+    # See also #header.
+    def body
+      return @body
+    end
+
+    # Sets the body of the message to the given value.  It should
+    # either be a String or an Array of RMail:Message objects.
+    def body=(s)
+      @body = s
+    end
+
+    # Returns the RMail::Header object.
+    #
+    # See also #body.
+    def header()
+      return @header
+    end
+
+    # Return true if the message consists of multiple parts.
+    def multipart?
+      @body.is_a?(Array)
+    end
+
+    # Add a part to the message.  After this message is called, the
+    # #multipart? method will return true and the #body method will
+    # #return an array of parts.
+    def add_part(part)
+      if @body.nil?
+	@body = [part]
+      elsif @body.is_a?(Array)
+        @body.push(part)
+      else
+	@body = [@body, part]
+      end
+    end
+
+    # Decode the body of this message.
+    #
+    # If the body of this message is encoded with
+    # <tt>quoted-printable</tt> or <tt>base64</tt>, this function will
+    # decode the data into its original form and return it as a
+    # String.  If the body is not encoded, it is returned unaltered.
+    #
+    # This only works when the message is not a multipart.  The
+    # <tt>Content-Transfer-Encoding:</tt> header field is consulted to
+    # determine the encoding of the body part.
+    def decode
+      raise TypeError, "Can not decode a multipart message." if multipart?
+      case header.fetch('content-transfer-encoding', '7bit').strip.downcase
+      when 'quoted-printable'
+        Utils.quoted_printable_decode(@body)
+      when 'base64'
+        Utils.base64_decode(@body)
+      else
+        @body
+      end
+    end
+
+    # Get the indicated part from a multipart message.
+    def part(i)
+      raise TypeError,
+        "Can not get part on a single part message." unless multipart?
+      @body[i]
+    end
+
+    # Access the epilogue string for this message.  The epilogue
+    # string is relevant only for multipart messages.  It is the text
+    # that occurs after all parts of the message and is generally nil.
+    attr :epilogue, true
+
+    # Access the preamble string for this message.  The preamble
+    # string is relevant only for multipart messages.  It is the text
+    # that occurs just before the first part of the message, and is
+    # generally nil or simple English text describing the nature of
+    # the message.
+    attr :preamble, true
+
+    # Returns the entire message in a single string.  This uses the
+    # RMail::Serialize class.
+    def to_s()
+      require 'rmail/serialize'
+      RMail::Serialize.new('').serialize(self)
+    end
+
+    # Return each part of this message
+    #
+    # FIXME: not tested
+    def each_part
+      raise TypeError, "not a multipart message" unless multipart?
+      @body.each do |part|
+        yield part
+      end
+    end
+
+    # Call the supplied block for each line of the message.  Each line
+    # will contain a trailing newline (<tt>\n</tt>).
+    def each()
+      # FIXME: this is incredibly inefficient!  The only users of this
+      # is RMail::Deliver -- get them to use a RMail::Serialize object.
+      to_s.each("\n") { |line|
+        yield line
+      }
+    end
+
+    # This is used by the RMail::Parser to set the MIME multipart
+    # delimiter strings found in the message.  These delimiters are
+    # then used when serializing the message again.
+    #
+    # Normal uses of RMail::Message will never use this method, and so
+    # it is left undocumented.
+    def set_delimiters(delimiters, boundary) # :nodoc:
+      raise TypeError, "not a multipart message" unless multipart?
+      raise ArgumentError, "delimiter array wrong size" unless
+        delimiters.length == @body.length + 1
+      @delimiters = delimiters.to_ary
+      @delimiters_boundary = boundary.to_str
+    end
+
+    # This is used by the serializing functions to retrieve the MIME
+    # multipart delimiter strings found while parsing the message.
+    # These delimiters are then used when serializing the message
+    # again.
+    #
+    # Normal uses of RMail::Message will never use this method, and so
+    # it is left undocumented.
+    def get_delimiters          # :nodoc:
+      unless multipart? and @delimiters and @delimiters_boundary and
+          @delimiters.length == @body.length + 1 and
+          header.param('content-type', 'boundary') == @delimiters_boundary
+        @delimiters = nil
+        @delimiters_boundary = nil
+      end
+      [ @delimiters, @delimiters_boundary ]
+    end
+
+  end
+end

data/lib/rmail/parser.rb

@@ -0,0 +1,412 @@
+#--
+#   Copyright (C) 2002, 2003, 2004 Matt Armstrong.  All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+# NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+#++
+# Implements the RMail::Parser, RMail::StreamParser and
+# RMail::StreamHandler classes.
+
+require 'rmail/message'
+require 'rmail/parser/multipart'
+
+module RMail
+
+  # = Overview
+  #
+  # An RMail::StreamHandler documents the set of methods a
+  # RMail::StreamParser handler must implement.  See
+  # RMail::StreamParser.parse.  This is a low level interface to the
+  # RMail message parser.
+  #
+  # = Order of Method Calls (Grammar)
+  #
+  # Calls to the methods of this class follow a specific grammar,
+  # described informally below.  The words in all caps are productions
+  # in the grammar, while the lower case words are method calls to
+  # this object.
+  #
+  # MESSAGE::         [ #mbox_from ] *( #header_field )
+  #                   ( BODY / MULTIPART_BODY )
+  #
+  # BODY::            *body_begin *( #body_chunk ) #body_end
+  #
+  # MULTIPART_BODY::  #multipart_body_begin
+  #                   *( #preamble_chunk )
+  #                   *( #part_begin MESSAGE #part_end)
+  #                   *( #epilogue_chunk )
+  #                   #multipart_body_end
+  #
+  # = Order of Method Calls (English)
+  #
+  # If the grammar above is not clear, here is a description in English.
+  #
+  # The parser begins calling #header_field, possibly calling
+  # #mbox_from for the first line.  Then it determines if the message
+  # was a MIME multipart message.
+  #
+  # If the message is a not a MIME multipart, the parser calls
+  # #body_begin once, then #body_chunk any number of times, then
+  # #body_end.
+  #
+  # If the message header is a MIME multipart message, then
+  # #multipart_body_begin is called, followed by any number of calls
+  # to #preamble_chunk.  Then for each part parsed, #part_begin is
+  # called, followed by a recursive set of calls described by the
+  # "MESSAGE" production above, and then #part_end.  After all parts
+  # are parsed, any number of calls to #epilogue_chunk are followed by
+  # a single call to #multipart_body_end.
+  #
+  # The recursive nature of MIME multipart messages is represented by
+  # the recursive invocation of the "MESSAGE" production in the
+  # grammar above.
+  class StreamHandler
+
+    # This method is called for Unix MBOX "From " lines in the message
+    # header, it calls this method with the text.
+    def mbox_from(line)
+    end
+
+    # This method is called when a header field is parsed.  The
+    # +field+ is the full text of the field, the +name+ is the name of
+    # the field and the +value+ is the field's value with leading and
+    # trailing whitespace removed.  Note that both +field+ and +value+
+    # may be multi-line strings.
+    def header_field(field, name, value)
+    end
+
+    # This method is called before a non-multipart message body is
+    # about to be parsed.
+    def body_begin
+    end
+
+    # This method is called with a string chunk of data from a
+    # non-multipart message body.  The string does not necessarily
+    # begin or end on any particular boundary.
+    def body_chunk(chunk)
+    end
+
+    # This method is called after all of the non-multipart message
+    # body has been parsed.
+    def body_end
+    end
+
+    # This method is called before a multipart message body is about
+    # to be parsed.
+    def multipart_body_begin
+    end
+
+    # This method is called with a chunk of data from a multipart
+    # message body's preamble.  The preamble is any text that appears
+    # before the first part of the multipart message body.
+    def preamble_chunk(chunk)
+    end
+
+    # This method is called when a part of a multipart body begins.
+    def part_begin
+    end
+
+    # This method is called when a part of a multipart body ends.
+    def part_end
+    end
+
+    # This method is called with a chunk of data from a multipart
+    # message body's epilogue.  The epilogue is any text that appears
+    # after the last part of the multipart message body.
+    def epilogue_chunk(chunk)
+    end
+
+    # This method is called after a multipart message body has been
+    # completely parsed.
+    #
+    # The +delimiters+ is an Array of strings, one for each boundary
+    # string found in the multipart body.  The +boundary+ is the
+    # boundary string used to delimit each part in the multipart body.
+    # You can normally ignore both +delimiters+ and +boundary+ if you
+    # are concerned only about message content.
+    def multipart_body_end(delimiters, boundary)
+    end
+  end
+
+  # The RMail::StreamParser is a low level message parsing API.  It is
+  # useful when you are interested in serially examining all message
+  # content but are not interested in a full object representation of
+  # the object.  See StreamParser.parse.
+  class StreamParser
+
+    class << self
+
+      # Parse a message from an input source.  This method returns
+      # nothing.  Instead, the supplied +handler+ is expected to
+      # implement the same methods as RMail::StreamHandler.  The
+      # message structure can be inferred from the methods called on
+      # the +handler+.  The +input+ can be any Ruby IO source or a
+      # String.
+      #
+      # This is a low level parsing API.  For a message parser that
+      # returns an RMail::Message object, see the RMail::Parser class.
+      # RMail::Parser is implemented using RMail::StreamParser.
+      def parse(input, handler)
+        RMail::StreamParser.new(input, handler).parse
+      end
+    end
+
+    def initialize(input, handler) # :nodoc:
+      @input = input
+      @handler = handler
+      @chunk_size = nil
+    end
+
+    def parse                   # :nodoc:
+      input = RMail::Parser::PushbackReader.new(@input)
+      input.chunk_size = @chunk_size if @chunk_size
+      parse_low(input, 0)
+      return nil
+    end
+
+    # Change the chunk size used to read the message.  This is useful
+    # mostly for testing, so we don't document it.
+    attr_accessor :chunk_size   # :nodoc:
+
+    private
+
+    def parse_low(input, depth)
+      multipart_boundary = parse_header(input, depth)
+      if multipart_boundary
+        parse_multipart_body(input, depth, multipart_boundary)
+      else
+        parse_singlepart_body(input, depth)
+      end
+    end
+
+    def parse_header(input, depth)
+      data = nil
+      header = nil
+      pushback = nil
+      boundary = nil
+      while chunk = input.read
+        data ||= ''
+        data << chunk
+        if data[0] == ?\n
+          # A leading newline in the message is seen when parsing the
+          # parts of a multipart message.  It means there are no
+          # headers.  The body part starts directly after this
+          # newline.
+          rest = data[1..-1]
+        else
+          header, rest = data.split(/\n\n/, 2)
+        end
+        break if rest
+      end
+      input.pushback(rest)
+      if header
+        mime = false
+        fields = header.split(/\n(?!\s)/)
+        if fields.first =~ /^From /
+          @handler.mbox_from(fields.first)
+          fields.shift
+        end
+        fields.each { |field|
+          if field =~ /^From /
+            @handler.mbox_from(field)
+          else
+            name, value = RMail::Header::Field.parse(field)
+            case name.downcase
+            when 'mime-version'
+              if value =~ /\b1\.0\b/
+                mime = true
+              end
+            when 'content-type'
+              # FIXME: would be nice to have a procedural equivalent
+              # to RMail::Header#param.
+              header = RMail::Header.new
+              header['content-type'] = value
+              boundary = header.param('content-type', 'boundary')
+            end
+            @handler.header_field(field, name, value)
+          end
+        }
+        unless mime or depth > 0
+          boundary = nil
+        end
+      end
+      return boundary
+    end
+
+    def parse_multipart_body(input, depth, boundary)
+      input = RMail::Parser::MultipartReader.new(input, boundary)
+      input.chunk_size = @chunk_size if @chunk_size
+
+      @handler.multipart_body_begin
+
+      # Reach each part, adding it to this entity as appropriate.
+      delimiters = []
+      while input.next_part
+        if input.preamble?
+          while chunk = input.read
+            @handler.preamble_chunk(chunk)
+          end
+        elsif input.epilogue?
+          while chunk = input.read
+            @handler.epilogue_chunk(chunk)
+          end
+        else
+          @handler.part_begin
+          parse_low(input, depth + 1)
+          @handler.part_end
+        end
+        delimiters << (input.delimiter || "") unless input.epilogue?
+      end
+      @handler.multipart_body_end(delimiters, boundary)
+    end
+
+    def parse_singlepart_body(input, depth)
+      @handler.body_begin
+      while chunk = input.read
+        @handler.body_chunk(chunk)
+      end
+      @handler.body_end
+    end
+
+  end
+
+  # The RMail::Parser class creates RMail::Message objects from Ruby
+  # IO objects or strings.
+  #
+  # To parse from a string:
+  #   message = RMail::Parser.read(the_string)
+  #
+  # To parse from an IO object:
+  #   message = File.open('my-message') { |f|
+  #     RMail::Parser.read(f)
+  #   }
+  #
+  # You can also parse from STDIN, etc.
+  #   message = RMail::Parser.read(STDIN)
+  #
+  # In all cases, the parser consumes all input.
+  class Parser
+
+    # This exception class is thrown when the parser encounters an
+    # error.
+    #
+    # Note: the parser tries hard to never throw exceptions -- this
+    # error is thrown only when the API is used incorrectly and not on
+    # invalid input.
+    class Error < StandardError; end
+
+    # Creates a new parser.  Messages of +message_class+ will be
+    # created by the parser.  By default, the parser will create
+    # RMail::Message objects.
+    def initialize()
+      @chunk_size = nil
+    end
+
+    # Parse a message from the IO object +io+ and return a new
+    # message.  The +io+ object can also be a string.
+    def parse(input)
+      handler = RMail::Parser::Handler.new
+      parser = RMail::StreamParser.new(input, handler)
+      parser.chunk_size = @chunk_size if @chunk_size
+      parser.parse
+      return handler.message
+    end
+
+    # Change the chunk size used to read the message.  This is useful
+    # mostly for testing.
+    attr_accessor :chunk_size
+
+    # Parse a message from the IO object +io+ and return a new
+    # message.  The +io+ object can also be a string.  This is just
+    # shorthand for:
+    #
+    #   RMail::Parser.new.parse(io)
+    def Parser.read(input)
+      Parser.new.parse(input)
+    end
+
+    class Handler < RMail::StreamHandler # :nodoc:
+      def initialize
+        @parts = [ RMail::Message.new ]
+        @preambles = []
+        @epilogues = []
+      end
+      def mbox_from(field)
+        @parts.last.header.mbox_from = field
+      end
+      def header_field(field, name, value)
+        @parts.last.header.add_raw(field)
+      end
+      def body_begin
+        @body = nil
+      end
+      def body_chunk(chunk)
+        if @body
+          @body << chunk
+        else
+          @body = chunk
+        end
+      end
+      def body_end
+        @parts.last.body = @body
+      end
+      def multipart_body_begin
+        @preambles.push(nil)
+        @epilogues.push(nil)
+      end
+      def preamble_chunk(chunk)
+        if @preambles.last
+          @preambles.last << chunk
+        else
+          @preambles[-1] = chunk
+        end
+      end
+      def epilogue_chunk(chunk)
+        if @epilogues.last
+          @epilogues.last << chunk
+        else
+          @epilogues[-1] = chunk
+        end
+      end
+      def multipart_body_end(delimiters, boundary)
+        @parts.last.preamble = @preambles.pop
+        @parts.last.epilogue = @epilogues.pop
+        if @parts.last.body.nil?
+          @parts.last.body = []
+        end
+        @parts.last.set_delimiters(delimiters, boundary)
+      end
+      def part_begin
+        @parts << RMail::Message.new
+      end
+      def part_end
+        part = @parts.pop
+        @parts.last.add_part(part)
+      end
+      def message
+        @parts.first
+      end
+    end
+
+  end
+end