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

mime 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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