rmail 0.17

data/lib/rmail/parser/multipart.rb

@@ -0,0 +1,217 @@
+#--
+#   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::MultipartReader class.
+
+module RMail
+  class Parser
+
+    require 'rmail/parser/pushbackreader'
+
+    # A simple interface to facilitate parsing a multipart message.
+    #
+    # The typical RubyMail user will have no use for this class.
+    # Although it is an example of how to use a PushbackReader, the
+    # typical RubyMail user will never use a PushbackReader either.
+    # ;-)
+    class MultipartReader < PushbackReader # :nodoc:
+
+      # Creates a MIME multipart parser.
+      #
+      # +input+ is an object supporting a +read+ method that takes one
+      # argument, a suggested number of bytes to read, and returns
+      # either a string of bytes read or nil if there are no more
+      # bytes to read.
+      #
+      # +boundary+ is the string boundary that separates the parts,
+      # without the "--" prefix.
+      #
+      # This class is a suitable input source when parsing recursive
+      # multiparts.
+      def initialize(input, boundary)
+        super(input)
+        escaped = Regexp.escape(boundary)
+        @delimiter_re = /(?:\G|\n)--#{escaped}(--)?\s*?(\n|\z)/
+        @might_be_delimiter_re = might_be_delimiter_re(boundary)
+        @caryover = nil
+        @chunks = []
+        @eof = false
+        @delimiter = nil
+        @delimiter_is_last = false
+        @in_epilogue = false
+        @in_preamble = true
+      end
+
+      # Returns the next chunk of data from the input stream as a
+      # string.  The chunk_size is passed down to the read method of
+      # this object's input stream to suggest a size to it, but don't
+      # depend on the returned data being of any particular size.
+      #
+      # If this method returns nil, you must call next_part to begin
+      # reading the next MIME part in the data stream.
+      def read_chunk(chunk_size)
+        chunk = read_chunk_low(chunk_size)
+        if chunk
+          if @in_epilogue
+            while more = read_chunk_low(chunk_size)
+              chunk << more
+            end
+          end
+        end
+        chunk
+      end
+
+      def read_chunk_low(chunk_size)
+
+        if @pushback
+          return standard_read_chunk(chunk_size)
+        end
+
+        input_gave_nil = false
+        loop {
+          return nil if @eof || @delimiter
+
+          unless @chunks.empty?
+            chunk, @delimiter, @delimiter_is_last = @chunks.shift
+            return chunk
+          end
+
+          chunk = standard_read_chunk(chunk_size)
+
+          if chunk.nil?
+            input_gave_nil = true
+          end
+          if @caryover
+            if chunk
+              @caryover << chunk
+            end
+            chunk = @caryover
+            @caryover = nil
+          end
+
+          if chunk.nil?
+            @eof = true
+            return nil
+          elsif @in_epilogue
+            return chunk
+          end
+
+          start = 0
+          found_last_delimiter = false
+
+          while !found_last_delimiter and
+              (start < chunk.length) and
+              (found = chunk.index(@delimiter_re, start))
+
+            if $~[2] == '' and !input_gave_nil
+              break
+            end
+
+            delimiter = $~[0]
+
+            # check if delimiter had the trailing --
+            if $~.begin(1)
+              found_last_delimiter = true
+            end
+
+            temp = if found == start
+                     nil
+                   else
+                     chunk[start, found - start]
+                   end
+
+            @chunks << [ temp, delimiter, found_last_delimiter ]
+
+            start = $~.end(0)
+          end
+
+          chunk = chunk[start..-1] if start > 0
+
+          # If something that looks like a delimiter exists at the end
+          # of this chunk, refrain from returning it.
+          unless found_last_delimiter or input_gave_nil
+            start = chunk.rindex(/\n/) || 0
+            if chunk.index(@might_be_delimiter_re, start)
+              @caryover = chunk[start..-1]
+              chunk[start..-1] = ''
+              chunk = nil if chunk.length == 0
+            end
+          end
+
+          unless chunk.nil?
+            @chunks << [ chunk, nil, false ]
+          end
+          chunk, @delimiter, @delimiter_is_last = @chunks.shift
+
+          if chunk
+            return chunk
+          end
+        }
+      end
+
+      # Start reading the next part.  Returns true if there is a next
+      # part to read, or false if we have reached the end of the file.
+      def next_part
+        if @eof
+          false
+        else
+          if @delimiter
+            @delimiter = nil
+            @in_preamble = false
+            @in_epilogue = @delimiter_is_last
+          end
+          true
+        end
+      end
+
+      # Call this to determine if #read is currently returning strings
+      # from the preamble portion of a mime multipart.
+      def preamble?
+        @in_preamble
+      end
+
+      # Call this to determine if #read is currently returning strings
+      # from the epilogue portion of a mime multipart.
+      def epilogue?
+        @in_epilogue
+      end
+
+      # Call this to retrieve the delimiter string that terminated the
+      # part just read.  This is cleared by #next_part.
+      def delimiter
+        @delimiter
+      end
+
+      private
+
+      def might_be_delimiter_re(boundary)
+        s = PushbackReader.maybe_contains_re("--" + boundary)
+        Regexp.new('(?:\A|\n)(?:' + s + '|\z)')
+      end
+
+    end
+  end
+end

data/lib/rmail/parser/pushbackreader.rb

@@ -0,0 +1,173 @@
+#--
+#   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::Parser::PushbackReader class.
+
+module RMail
+  class Parser
+
+    class Error < StandardError; end
+
+    # A utility class for reading from an input source in an efficient
+    # chunked manner.
+    #
+    # The idea is to read data in descent sized chunks (the default is
+    # 16k), but provide a way to "push back" some of the chunk if we
+    # read too much.
+    #
+    # This class is useful only as a base class for other readers --
+    # e.g. a reader that parses MIME multipart documents, or a reader
+    # that understands one or more mailbox formats.
+    #
+    # The typical RubyMail user will have no interest in this class.
+    # ;-)
+    class PushbackReader        # :nodoc:
+
+      # Create a PushbackReader and have it read from a given input
+      # source.
+      #
+      # The input source must either be a String or respond to the
+      # "read" method in the same way as an IO object.
+      def initialize(input)
+        unless defined? input.read(1)
+          unless input.is_a?(String)
+            raise ArgumentError, "input object not IO or String"
+          end
+          @pushback = input
+          @input = nil
+        else
+          @pushback = nil
+          @input = input
+        end
+        @chunk_size = 16384
+      end
+
+      # Read a chunk of input.  The "size" argument is just a
+      # suggestion, and more or fewer bytes may be returned.  If
+      # "size" is nil, then return the entire rest of the input
+      # stream.
+      def read(size = @chunk_size)
+        case size
+        when nil
+          chunk = nil
+          while temp = read(@chunk_size)
+            if chunk
+              chunk << temp
+            else
+              chunk = temp
+            end
+          end
+          chunk
+        when Fixnum
+          read_chunk(size)
+        else
+          raise ArgumentError,
+            "Read size (#{size.inspect}) must be a Fixnum or nil."
+        end
+      end
+
+      # Read a chunk of a given size.  Unlike #read, #read_chunk must
+      # be passed a chunk size, and cannot be passed nil.
+      #
+      # This is the function that should be re-defined in subclasses
+      # for specialized behavior.
+      def read_chunk(size)
+        standard_read_chunk(size)
+      end
+
+      # The standard implementation of read_chunk.  This can be
+      # convenient to call from derived classes when super() isn't
+      # easy to use.
+      def standard_read_chunk(size)
+        unless size.is_a?(Fixnum) && size > 0
+          raise ArgumentError,
+            "Read size (#{size.inspect}) must be greater than 0."
+        end
+        if @pushback
+          chunk = @pushback
+          @pushback = nil
+        elsif ! @input.nil?
+          chunk = @input.read(size)
+        end
+        return chunk
+      end
+
+      # Push a string back.  This will be the next chunk of data
+      # returned by #read.
+      #
+      # Because it has not been needed and would compromise
+      # efficiency, only one chunk of data can be pushed back between
+      # successive calls to #read.
+      def pushback(string)
+        raise RMail::Parser::Error,
+          'You have already pushed a string back.' if @pushback
+        @pushback = string
+      end
+
+      # Retrieve the chunk size of this reader.
+      attr_reader :chunk_size
+
+      # Set the chunk size of this reader in bytes.  This is useful
+      # mainly for testing, though perhaps some operations could be
+      # optimized by tweaking this value.  The chunk size must be a
+      # Fixnum greater than 0.
+      def chunk_size=(size)
+        unless size.is_a?(Fixnum)
+          raise ArgumentError, "chunk size must be a Fixnum"
+        end
+        unless size >= 1
+          raise ArgumentError, "invalid size #{size.inspect} given"
+        end
+        @chunk_size = size
+      end
+
+      # Returns true if the next call to read_chunk will return nil.
+      def eof
+        @pushback.nil? and (@input.nil? or @input.eof)
+      end
+
+      # Creates a regexp that'll match the given boundary string in
+      # its entirely anywhere in a string, or any partial prefix of
+      # the boundary string so long as the match is anchored at the
+      # end of the string.  This is useful for various subclasses of
+      # PushbackReader that need to know if a given input chunk might
+      # contain (or contain just the beginning of) an interesting
+      # string.
+      def self.maybe_contains_re(boundary)
+        left = Regexp.quote(boundary[0,1])
+        right = ''
+        boundary[1..-1].each_byte { |ch|
+          left << '(?:'
+          left << Regexp.quote(ch.chr)
+          right << '|\z)'
+        }
+        left + right
+      end
+
+    end
+
+  end
+end

data/lib/rmail/serialize.rb

@@ -0,0 +1,190 @@
+#--
+#   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::Serialize class.
+
+module RMail
+
+  # The RMail::Serialize class writes an RMail::Message object into an
+  # IO object or string.  The result is a standard mail message in
+  # text form.
+  #
+  # To do this, you pass the RMail::Message object to the
+  # RMail::Serialize object.  RMail::Serialize can write into any
+  # object supporting the << method.
+  #
+  # As a convenience, RMail::Serialize.write is a class method you can
+  # use directly:
+  #
+  #  # Write to a file
+  #  File.open('my-message', 'w') { |f|
+  #    RMail::Serialize.write(f, message)
+  #  }
+  #
+  # # Write to a new string
+  # string = RMail::Serialize.write('', message)
+  class Serialize
+
+    @@boundary_count = 0
+
+    # Initialize this Serialize object with an output stream.  If
+    # escape_from is not nil, lines with a leading From are escaped.
+    def initialize(output, escape_from = nil)
+      @output = output
+      @escape_from = escape_from
+    end
+
+    # Serialize a given message into this object's output object.
+    def serialize(message)
+      calculate_boundaries(message) if message.multipart?
+      serialize_low(message)
+    end
+
+    # Serialize a message into a given output object.  The output
+    # object must support the << method in the same way that an IO or
+    # String object does.
+    def Serialize.write(output, message)
+      Serialize.new(output).serialize(message)
+    end
+
+    private
+
+    def serialize_low(message, depth = 0)
+      if message.multipart?
+        delimiters, delimiters_boundary = message.get_delimiters
+        unless delimiters
+          boundary = "\n--" + message.header.param('Content-Type', 'boundary')
+          delimiters = Array.new(message.body.length + 1, boundary + "\n")
+          delimiters[-1] = boundary + "--\n"
+        end
+
+        @output << message.header.to_s
+
+        if message.body.length > 0 or message.preamble or
+            delimiters.last.length > 0
+          @output << "\n"
+        end
+
+        if message.preamble
+          @output << message.preamble
+        end
+
+        delimiter = 0
+        message.each_part { |part|
+          @output << delimiters[delimiter]
+          delimiter = delimiter.succ
+          serialize_low(part, depth + 1)
+        }
+
+        @output << delimiters[delimiter]
+
+        if message.epilogue
+          @output << message.epilogue
+        end
+
+      else
+        @output << message.header.to_s
+        unless message.body.nil?
+          @output << "\n"
+          @output << message.body
+          if depth == 0 and message.body.length > 0 and
+              message.body[-1] != ?\n
+            @output << "\n"
+          end
+        end
+      end
+      @output
+    end
+
+    # Walk the multipart tree and make sure the boundaries generated
+    # will actually work.
+    def calculate_boundaries(message)
+      calculate_boundaries_low(message, [])
+      unless message.header['MIME-Version']
+        message.header['MIME-Version'] = "1.0"
+      end
+    end
+
+    def calculate_boundaries_low(part, boundaries)
+      # First, come up with a candidate boundary for this part and
+      # save it in our list of boundaries.
+      boundary = make_and_set_unique_boundary(part, boundaries)
+
+      # Now walk through each part and make sure the boundaries are
+      # suitable.  We dup the boundaries array before recursing since
+      # sibling multipart can re-use boundary strings (though it isn't
+      # a good idea).
+      boundaries.push(boundary)
+      part.each_part { |p|
+        calculate_boundaries_low(p, boundaries) if p.multipart?
+      }
+      boundaries.pop
+    end
+
+    # Generate a random boundary
+    def generate_boundary
+      @@boundary_count += 1
+      t = Time.now
+      sprintf("=-%d-%d-%d-%d-%d-=",
+              t.tv_sec.to_s,
+              t.tv_usec.to_s,
+              Process.pid.to_s,
+              rand(10000),
+              @@boundary_count)
+    end
+
+    # Returns a boundary that will probably work out.  Extracts any
+    # existing boundary from the header, but will generate a default
+    # one if the header doesn't have one set yet.
+    def make_and_set_unique_boundary(part, boundaries)
+      candidate = part.header.param('content-type', 'boundary')
+      unique = make_unique_boundary(candidate || generate_boundary, boundaries)
+      if candidate.nil? or candidate != unique
+        part.header.set_boundary(unique)
+      end
+      unique
+    end
+
+    # Make the passed boundary unique among the passed boundaries and
+    # return it.
+    def make_unique_boundary(boundary, boundaries)
+      continue = true
+      while continue
+        continue = false
+        boundaries.each do |existing|
+          if boundary == existing[0, boundary.length]
+            continue = true
+            break
+          end
+        end
+        break unless continue
+        boundary = generate_boundary
+      end
+      boundary
+    end
+
+  end
+end