RubyGems - mime - Versions diffs - 0.3.0 → 0.4.0 - Mend

mime 0.3.0 → 0.4.0

Files changed (35) hide show

data/README.rdoc +192 -140
data/lib/mime/composite_media.rb +230 -0
data/lib/mime/content_formats/text_flowed.rb +6 -6
data/lib/mime/discrete_media.rb +73 -0
data/lib/mime/discrete_media_factory.rb +19 -13
data/lib/mime/header.rb +48 -0
data/lib/mime/headers/internet.rb +124 -27
data/lib/mime/headers/mime.rb +38 -27
data/lib/mime/mail.rb +51 -0
data/lib/mime/media.rb +30 -0
data/lib/mime/parser.rb +1 -1
data/lib/mime.rb +27 -9
data/test/scaffold/application.msg +2 -5
data/test/scaffold/audio.msg +2 -5
data/test/scaffold/image.msg +0 -0
data/test/scaffold/multipart_alternative.msg +7 -7
data/test/scaffold/multipart_alternative_related.msg +0 -0
data/test/scaffold/multipart_form_data_file_and_text.msg +0 -0
data/test/scaffold/multipart_form_data_mixed.msg +0 -0
data/test/scaffold/multipart_form_data_text.msg +12 -12
data/test/scaffold/multipart_mixed_inline_and_attachment.msg +0 -0
data/test/scaffold/multipart_mixed_inline_and_attachment2.msg +0 -0
data/test/scaffold/multipart_related.msg +0 -0
data/test/scaffold/rfc822_composite.msg +0 -0
data/test/scaffold/{plain_text_email.msg → rfc822_discrete.msg} +5 -5
data/test/scaffold/text.msg +2 -5
data/test/scaffold/video.msg +2 -5
data/test/test_mime.rb +323 -150
data/test/test_text_flowed.rb +1 -1
metadata +13 -12
data/lib/mime/composite_media_type.rb +0 -169
data/lib/mime/discrete_media_type.rb +0 -78
data/lib/mime/header_container.rb +0 -32
data/lib/mime/media_type.rb +0 -51
data/lib/mime/message.rb +0 -61

data/lib/mime/composite_media.rb ADDED Viewed

@@ -0,0 +1,230 @@
+module MIME
+  #
+  # Composite media types allow encapsulating, mixing, and hierarchical
+  # structuring of entities of different types within a single message.
+  # Therefore, a CompositeMedia body is composed of one or more CompositeMedia
+  # and/or DiscreteMedia objects.
+  #
+  # CompositeMedia implements Content-Disposition for dictating presentation
+  # style of body entities via #add, #attach, and #inline. For more information
+  # on disposition parameters, such as filename, size, and modification-date,
+  # see https://tools.ietf.org/html/rfc2183.
+  #
+  # This class is abstract.
+  #
+  class CompositeMedia < Media
+    class Body
+      #
+      # Create new composite body.
+      #
+      def initialize boundary
+        @boundary = boundary
+        @body = Array.new
+      end
+      #
+      # Format the CompositeMedia object as a MIME message.
+      #
+      def to_s
+        all_entities = @body.join("\r\n--#{@boundary}\r\n")
+        "--#{@boundary}\r\n#{all_entities}\r\n--#{@boundary}--\r\n"
+      end
+      #
+      # Add +entity+ to the composite body.
+      #
+      def add entity
+        @body.push(entity)
+      end
+    end
+    attr_reader :boundary
+    def initialize content_type
+      AbstractClassError.no_instantiation(self, CompositeMedia)
+      @boundary = "Boundary_#{ID.generate_id}"  # delimits body entities
+      super(Body.new(boundary), content_type, 'boundary' => boundary)
+    end
+    #
+    # Add a Media +entity+ to the message.
+    #
+    # The entity will be added to the main body of the message with no
+    # disposition specified. Presentation of the entity will be dictated by
+    # the display user agent.
+    #
+    # === Text and HTML Multipart/Alternative message
+    #
+    # A display user agent may only be capable of displaying plain text. If so,
+    # it will choose to display the Text/Plain entity. However, if it is capable
+    # of displaying HTML, it may choose to display the Text/HTML version.
+    #
+    #   msg = MIME::Multipart::Alternative.new
+    #   msg.add(MIME::Text.new('plain text'))
+    #   msg.add(MIME::Text.new('<html>html text</html>', 'html'))
+    #
+    # The order in which the entities are added is significant. Add the simplest
+    # representations first.
+    #
+    def add entity
+      raise Error.new('can only add Media objects') unless entity.is_a? Media
+      @body.add(entity)
+    end
+    #
+    # Attach a Media +entity+ to the message.
+    #
+    # The entity will be presented as separate from the main body of the
+    # message. Thus, display of the entity will not be automatic, but contingent
+    # upon some further action of the user. For example, the display user agent
+    # may present an icon representation of the entity, which the user can
+    # select to view or save the entity.
+    #
+    # === Attachment with filename and size parameters:
+    #
+    #   f = File.open('file.txt')
+    #   file = MIME::Text.new(f.read)
+    #   text = MIME::Text.new('See the attached file.')
+    #
+    #   msg = MIME::Multipart::Mixed.new
+    #   msg.inline(text)
+    #   msg.attach(file, 'filename' => f.path, 'size' => f.size)
+    #
+    def attach entity, params = {}
+      entity.set_disposition('attachment', params)
+      add(entity)
+    end
+    #
+    # Inline a Media +entity+ in the message.
+    #
+    # The entity will be embedded within the main body of the message. Thus,
+    # display of the entity will be automatic upon display of the message.
+    # Inline entities should be added in the order in which they occur within
+    # the message.
+    #
+    # === Message with two embedded images:
+    #
+    #  msg = MIME::Multipart::Mixed.new
+    #  msg.inline(MIME::Image.new(File.read('screenshot1.png'), 'png'))
+    #  msg.inline(MIME::Image.new(File.read('screenshot2.png'), 'png'))
+    #  msg.description = 'My screenshots'
+    #
+    def inline entity, params = {}
+      entity.set_disposition('inline', params)
+      add(entity)
+    end
+  end
+  #
+  # Message is intended to encapsulate another message. In particular, the
+  # <em>message/rfc822</em> content type is used to encapsulate RFC 822
+  # messages.
+  #
+  # TODO Implement
+  #
+  class Message < CompositeMedia
+  end
+  #
+  # The abstract base class for all multipart message subtypes. The entities of
+  # a multipart message are delimited by a unique boundary.
+  #
+  class Multipart < CompositeMedia
+    def initialize media_subtype
+      AbstractClassError.no_instantiation(self, Multipart)
+      super("multipart/#{media_subtype}")
+    end
+  end
+  #
+  # The Alternative subtype indicates that each contained entity is an
+  # alternatively formatted version of the same content. The most complex
+  # version should be added to the message first, i.e. it will be sequentially
+  # last in the message.
+  #
+  class Multipart::Alternative < Multipart
+    #
+    # Returns a Multipart::Alternative object with a content type of
+    # multipart/alternative.
+    #
+    def initialize
+      super('alternative')
+    end
+  end
+  #
+  # The FormData subtype expresses values for HTML form data submissions.
+  # ---
+  # RFCs consulted during implementation:
+  #
+  # * RFC-1867  Form-based File Upload in HTML
+  # * RFC-2388  Returning Values from Forms: multipart/form-data
+  #
+  class Multipart::FormData < Multipart
+    #
+    # Returns a Multipart::FormData object with a content type of
+    # multipart/form-data.
+    #
+    def initialize
+      super('form-data')
+    end
+    #
+    # Add the Media object, +entity+, to the FormData object. +name+ is
+    # typically an HTML input tag variable name. If the input tag is of type
+    # _file_, then +filename+ must be specified to indicate a file upload.
+    #
+    def add entity, name, filename = nil
+      entity.set_disposition('form-data', 'name' => name, 'filename' => filename)
+      super(entity)
+    end
+  end
+  #
+  # The Mixed subtype aggregates contextually independent entities.
+  #
+  class Multipart::Mixed < Multipart
+    #
+    # Returns a Multipart::Mixed object with a content type of
+    # multipart/mixed.
+    #
+    def initialize
+      super('mixed')
+    end
+  end
+  #
+  # The Related subtype aggregates multiple related entities. The message
+  # consists of a root (the first entity) which references subsequent inline
+  # entities. Message entities should be referenced by their Content-ID header.
+  # The syntax of a reference is unspecified and is instead dictated by the
+  # encoding or protocol used in the entity.
+  # ---
+  # RFC consulted during implementation:
+  #
+  # * RFC-2387  The MIME Multipart/Related Content-type
+  #
+  class Multipart::Related < Multipart
+    #
+    # Returns a Multipart::Related object with a content type of
+    # multipart/related.
+    #
+    def initialize
+      super('related')
+    end
+  end
+end

data/lib/mime/content_formats/text_flowed.rb CHANGED Viewed

@@ -41,15 +41,15 @@ module MIME::ContentFormats
     # Encode plain +text+ into flowed format, reducing long lines to +max+
     # characters or less using soft line breaks (i.e., SPACE+CRLF).
     #
-    # The default +max+ line length is 79 characters. According to the RFC, 66
-    # and 72 characters is also common.
+    # According to the RFC, the +max+ flowed line length is 79 characters. Line
+    # lengths of 66 and 72 characters are common.
     #
     # The features of RFC 2646, such as line quoting and space-stuffing,
     # are not implemented.
     #
     def self.encode(text, max = MAX_FLOWED_LINE)
-      if max > 79
-        raise ArgumentError, 'flowed lines must be 79 characters or less'
+      if max > MAX_FLOWED_LINE
+        raise ArgumentError, "flowed lines must be #{MAX_FLOWED_LINE} characters or less"
       end
       out = []
@@ -83,7 +83,7 @@ module MIME::ContentFormats
                 if word.size < max
                   line << word + char
                 else
-                  word.scan(/.{1,#{MAX_SMTP_LINE}}/) {|s| out << s }
+                  word.scan(/.{1,#{MIME::MAX_LINE_LENGTH}}/) {|s| out << s }
                 end
               end
               word.clear
@@ -98,7 +98,7 @@ module MIME::ContentFormats
               out << line + word
             else
               out << line unless line.empty?
-              word.scan(/.{1,#{MAX_SMTP_LINE}}/) {|s| out << s }
+              word.scan(/.{1,#{MIME::MAX_LINE_LENGTH}}/) {|s| out << s }
             end
           elsif ! line.empty?
             out << line

data/lib/mime/discrete_media.rb ADDED Viewed

@@ -0,0 +1,73 @@
+module MIME
+  #
+  # Discrete media must be handled by non-MIME mechanisms; they are opaque to
+  # MIME processors. Therefore, the body of a DiscreteMedia object does not need
+  # further MIME processing.
+  #
+  # This class is abstract.
+  #
+  class DiscreteMedia < Media
+    def initialize(content, content_type, content_params)
+      AbstractClassError.no_instantiation(self, DiscreteMedia)
+      super
+    end
+  end
+  #
+  # Application is intended for discrete data that is to be processed by some
+  # type of application program. The body contains information which must be
+  # processed by an application before it is viewable or usable by a user.
+  #
+  # Application is the catch all class. If your content cannot be identified as
+  # another DiscreteMedia, then it is application media.
+  #
+  class Application < DiscreteMedia
+    def initialize(body, subtype = 'octet-stream', params = {})
+      super(body, "application/#{subtype}", params)
+    end
+  end
+  #
+  # Audio is intended for discrete audio content. The +subtype+ indicates the
+  # specific audio format, such as *mpeg* or *midi*.
+  #
+  class Audio < DiscreteMedia
+    def initialize(body, subtype = 'basic', params = {})
+      super(body, "audio/#{subtype}", params)
+    end
+  end
+  #
+  # Image is intented for discrete image content. The +subtype+ indicates the
+  # specific image format, such as *jpeg* or *gif*.
+  #
+  class Image < DiscreteMedia
+    def initialize(body, subtype = 'jpeg', params = {})
+      super(body, "image/#{subtype}", params)
+    end
+  end
+  #
+  # Text is intended for content which is principally textual in form. The
+  # +subtype+ indicates the specific text type, such as *plain* or *html*.
+  #
+  class Text < DiscreteMedia
+    def initialize(body, subtype = 'plain', params = {})
+      super(body, "text/#{subtype}", params)
+    end
+  end
+  #
+  # Video is intended for discrete video content. The content +subtype+
+  # indicates the specific video format. The RFC describes video media as
+  # content that contains a time-varying-picture image, possibly with color and
+  # coordinated sound.
+  #
+  class Video < DiscreteMedia
+    def initialize(body, subtype = 'mpeg', params = {})
+      super(body, "video/#{subtype}", params)
+    end
+  end
+end

data/lib/mime/discrete_media_factory.rb CHANGED Viewed

@@ -1,16 +1,20 @@
 module MIME
   #
-  # Module used only for initializing derived DiscreteMediaType objects.
+  # Module used only for initializing derived DiscreteMedia objects.
   #
   module DiscreteMediaFactory
+    module DispositionParameters
+      attr_accessor :path, :size
+    end
     class << self
       include ContentTypes
       #
-      # Creates a corresponding DiscreteMediaType subclass object for the given
+      # Creates a corresponding DiscreteMedia subclass object for the given
       # +file+ based on +file+'s filename extension. +file+ can be a file path
       # or File object.
       #
@@ -22,14 +26,16 @@ module MIME
       # +path+ method is utilized by other methods in the MIME library,
       # therefore, eliminating redundant and explicit filename assignments.
       #
-      # ==== Comparison Example
+      # === Comparison Example
       #
-      #  entity1 = open('/tmp/file1.txt')
-      #  entity2 = DiscreteMediaFactory.create('/tmp/file2.txt')
+      #  file1 = '/tmp/file1.txt'
+      #  file2 = '/tmp/file2.txt'
+      #  entity1 = Text.new(File.read(file1))
+      #  entity2 = DiscreteMediaFactory.create(file2)
       #
       #  mixed_msg = Multipart::Mixed.new
-      #  mixed_msg.attach_entity(entity1.read, entity.path)
-      #  mixed_msg.attach_entity(entity2) # no path needed
+      #  mixed_msg.attach(entity1, 'filename' => file1)
+      #  mixed_msg.attach(entity2) # filename automatically added
       #
       def create file, content_type = nil
         if file.is_a? File
@@ -49,15 +55,15 @@ module MIME
         media_obj =
           case type
-          when 'application'; ApplicationMedia.new(cntnt, subtype)
-          when 'audio'      ; AudioMedia.new(cntnt, subtype)
-          when 'image'      ; ImageMedia.new(cntnt, subtype)
-          when 'text'       ; TextMedia.new(cntnt, subtype)
-          when 'video'      ; VideoMedia.new(cntnt, subtype)
+          when 'application'; Application.new(cntnt, subtype)
+          when 'audio'      ; Audio.new(cntnt, subtype)
+          when 'image'      ; Image.new(cntnt, subtype)
+          when 'text'       ; Text.new(cntnt, subtype)
+          when 'video'      ; Video.new(cntnt, subtype)
           else raise UnknownContentError, "invalid content type: #{ctype}"
           end
-        class << media_obj;  attr_accessor :path  end
+        media_obj.extend(DispositionParameters)
         media_obj.path = fname
         media_obj
       end

data/lib/mime/header.rb ADDED Viewed

@@ -0,0 +1,48 @@
+module MIME
+  #
+  # Header section for Internet and MIME messages.
+  #
+  class Header
+    def initialize
+      @headers = Hash.new
+    end
+    #
+    # Convert all headers to their string equivalents and join them using the
+    # RFC 2822 CRLF line separator.
+    #--
+    # TODO fold lines to 78 chars.
+    # word.scan(/(.,?){1,78}/) OR word.split
+    #
+    def to_s
+      @headers.to_a.map {|kv| kv.join(": ")}.join("\r\n")
+    end
+    #
+    # Get header value associated with +name+.
+    #
+    def get name
+      _, value = @headers.find {|k,v| name.downcase == k.downcase }
+      value
+    end
+    #
+    # Set header +name+ to +value+. If a header of the same name exists it will
+    # be overwritten. Header names are _case-insensitive_.
+    #
+    def set name, value
+      delete(name)
+      @headers.store(name, value)
+    end
+    #
+    # Delete header associated with +name+.
+    #
+    def delete name
+      @headers.delete_if {|k| name.downcase == k.downcase }
+    end
+  end
+end

data/lib/mime/headers/internet.rb CHANGED Viewed

@@ -4,8 +4,18 @@ module MIME
     #
     # The RFC 2822 Internet message header fields.
     #
+    # Mailbox fields #to, #from, #cc, #bcc, and #reply_to may be a single email
+    # address, an array of email addresses, or a hash of _email_ => _name_
+    # pairs. When using a hash, set _name_ to +nil+ to omit email display name.
+    # The #sender field is a special case and contain only a single mailbox.
+    #
     module Internet
+      # Internet message character specifications (RFC 5322)
+      ATOM     = /[[:alnum:]!#\$%&'*+\/=?^_`{|}~-]/
+      DOT_ATOM = /^#{ATOM}+(#{ATOM}|\.)*$/
+      SPECIALS = /[()<>\[\]:;@\,."]/
       attr_reader(
         # Required Headers
         :to,
@@ -15,76 +25,163 @@ module MIME
         # Optional Headers
         :cc,
         :bcc,
+        :sender,
         :reply_to,
         :message_id,
+        :in_reply_to,
+        :references,
         :comments,
         :keywords,
         :subject
       )
+      #
+      # Origination date at which the creator of the message indicated that the
+      # message was complete and ready to enter the mail delivery system.
+      #
       def date= date
         @date = date
-        headers.add('Date', @date)
+        headers.set('Date', date.rfc2822)
       end
-      def from= list
-        @from = stringify_email_list(list)
-        headers.add('From', @from)
+      #
+      # Person(s) or system(s) responsible for writing the message.
+      #
+      def from= mailbox
+        @from = mailbox
+        headers.set('From', stringify_mailbox(mailbox))
+      end
+      #
+      # Mailbox of the agent responsible for actual transmission of the message.
+      # Sender field is required if the From field contains multiple mailboxes.
+      #
+      # === Example scenario
+      # If a secretary were to send a message for another person, the mailbox of
+      # the secretary would appear in the Sender field and the mailbox of the
+      # actual author would appear in the From field.
+      #
+      def sender= mailbox
+        if (mailbox.is_a?(Hash) || mailbox.is_a?(Array)) && mailbox.size != 1
+          raise ArgumentError, '"Sender" must be a single mailbox specification'
+        end
+        @sender = mailbox
+        headers.set('Sender', stringify_mailbox(mailbox))
       end
-      def to= list
-        @to = stringify_email_list(list)
-        headers.add('To', @to)
+      #
+      # Mailbox(es) of the primary recipient(s).
+      #
+      def to= mailbox
+        @to = mailbox
+        headers.set('To', stringify_mailbox(mailbox))
       end
-      def cc= list
-        @cc = stringify_email_list(list)
-        headers.add('Cc', @cc)
+      #
+      # Mailbox(es) of others who are to receive the message, though the content
+      # of the message may not be directed at them; "Carbon Copy."
+      #
+      def cc= mailbox
+        @cc = mailbox
+        headers.set('Cc', stringify_mailbox(mailbox))
       end
-      def bcc= list
-        @bcc = stringify_email_list(list)
-        headers.add('Bcc', @bcc)
+      #
+      # Mailbox(es) of recipients of the message whose addresses are not to be
+      # revealed to other recipients of the message; "Blind Carbon Copy."
+      #
+      def bcc= mailbox
+        @bcc = mailbox
+        headers.set('Bcc', stringify_mailbox(mailbox))
       end
-      def reply_to= list
-        @reply_to = stringify_email_list(list)
-        headers.add('Reply-To', @reply_to)
+      #
+      # Mailbox(es) to which the author suggests that replies be sent.
+      #
+      def reply_to= mailbox
+        @reply_to = mailbox
+        headers.set('Reply-To', stringify_mailbox(mailbox))
       end
+      #
+      # Globally unique identifier of the message.
       #
       # The message +id+ must contain an embedded "@" symbol. An example +id+
       # might be <em>some-unique-id@domain.com</em>.
       #
       def message_id= id
-        @message_id = "<#{id}>"
-        headers.add('Message-ID', @message_id)
+        @message_id = id
+        headers.set('Message-ID', "<#{id}>")
+      end
+      #
+      # The +id+ of the message to which this message is a reply.
+      #--
+      # TODO fully implement and test
+      #
+      def in_reply_to= id
+        @in_reply_to = id
+        headers.set('In-Reply-To', "<#{id}>")
+      end
+      #
+      # The +id+ used to identify a "thread" of conversation.
+      #--
+      # TODO fully implement and test
+      #
+      def references= id
+        @references = id
+        headers.set('References', "<#{id}>")
       end
+      #
+      # Additional comments about the message content.
+      #
       def comments= comments
         @comments = comments
-        headers.add('Comments', @comments)
+        headers.set('Comments', comments)
       end
+      #
+      # Comma-separated list of important words and phrases that might be useful
+      # for the recipient.
+      #
       def keywords= keywords
         @keywords = keywords
-        headers.add('Keywords', @keywords)
+        headers.set('Keywords', keywords)
       end
+      #
+      # The message topic.
+      #
       def subject= subject
         @subject = subject
-        headers.add('Subject', @subject)
+        headers.set('Subject', subject)
       end
       private
-      #
-      # +list+ may be a single email address or a Hash of _email_ => _name_
-      # pairs. Set _name_ to nil when it is unknown.
-      #
-      def stringify_email_list list
-        list.map {|email, name| name ? "#{name} <#{email}>" : email}.join(', ')
+      def stringify_mailbox mailbox
+        case mailbox
+        when Hash
+          mailbox.map do |email, name|
+            if name
+              if name =~ SPECIALS
+                name.gsub!('"', '\"')
+                %["#{name}" <#{email}>]
+              else
+                %[#{name} <#{email}>]
+              end
+            else
+              email
+            end
+          end.join(', ')
+        when Array
+          mailbox.join(', ')
+        else
+          return mailbox
+        end
       end
     end