mime 0.1

data/README

@@ -0,0 +1,256 @@
+== Multipurpose Internet Mail Extensions (MIME)
+
+A library for building RFC compliant Multipurpose Internet Mail Extensions
+(MIME) messages. It can be used to construct standardized MIME messages for use
+in client/server communications, such as Internet mail or HTTP
+multipart/form-data transactions.
+
+
+== See
+
+* MIME for RFCs used to implement the library (other RFCs scattered throughout)
+* MIME::CompositeMediaType for a description of composite media types
+* MIME::DiscreteMediaType for a description of discrete media types
+* MIME::DiscreteMediaFactory for easy programming of discrete media types
+
+
+== Media Type Inheritance Heirarchy
+
+     MediaType*
+         ^
+         |
+         |--DiscreteMediaType*
+         |      ^
+         |      |
+         |      |--ApplicationMedia
+         |      |--AudioMedia
+         |      |--ImageMedia
+         |      |--TextMedia
+         |      +--VideoMedia
+         |
+         +--CompositeMediaType*
+                ^
+                |
+                |--MessageMedia**
+                |      ^
+                |      |
+                |      |--ExternalBody**
+                |      |--Partial**
+                |      +--RFC822**
+                |
+                +--MultipartMedia*
+                       ^
+                       |
+                       |--Alternative
+                       |--Digest**
+                       |--Encrypted**
+                       |--FormData
+                       |--Mixed
+                       |--Parallel**
+                       |--Related
+                       |--Report**
+                       +--Signed**
+    
+     *  Abstract Class
+     ** Not implemented
+
+
+== MIME Message Structure
+
+
+                      ---------------------+
+    +----------------+                     |
+    |  RFC822 & MIME |                     |
+    | Message Headers|                     |
+    +----------------+                     |
+                       ---+                |
+    +----------------+    |                |
+    |  MIME Headers  |    |                |
+    +----------------+    |---MIME Entity  |
+    +----------------+    |      (N)       |
+    |      Body      |    |                |---RFC822 Message
+    +----------------+    |                |
+                       ---+                |
+                       ---+                |
+    +----------------+    |                |
+    |  MIME Headers  |    |                |
+    +----------------+    |---MIME Entity  |
+    +----------------+    |     (N+1)      |
+    |      Body      |    |                |
+    +----------------+    |                |
+                       ---+                |
+                      ---------------------+
+
+Each <em>MIME Entity</em> must be a discrete (MIME::DiscreteMediaType) or
+composite (MIME::CompositeMediaType) media type. Because MIME is recursive,
+composite entity bodies may contain other composite or discrete entites and so
+on. However, discrete entities are non-recursive and contain only non-MIME
+bodies.
+
+ 
+== Examples
+
+<em>The following examples imply that the MIME module is included.</em>
+
+
+=== Two ways to instantiate a DiscreteMediaType object using a file path
+
+  fpath = '/tmp/data.xml'
+  text_media = open(fpath) {|f| TextMedia.new(f.read, 'text/xml')}
+  text_media = DiscreteMediaFactory.create(fpath)
+
+
+=== Simple text/plain RFC822 email
+
+  msg = Message.new                     # creates a blank message with date and message ID headers
+  msg.date = (Time.now - 3600).rfc2822  # specify a different date
+  msg.subject = 'This is important'
+  msg.headers.add('X-Priority', 'high')  # custom header
+
+  msg.body = TextMedia.new('hello, it is me!')
+  #
+  # The following snippets are equivalent to the previous line.
+  #
+  #   msg.body = "\r\nhello, it is me!"
+  #   msg.header.add('Content-Type', 'text/plain; charset=us-ascii')
+  #
+  #   --OR--
+  #
+  #   msg.body = "Content-Type: text/plain; charset=us-ascii\r\n\r\nhello, it is me!"
+
+  msg.to = {
+    's13xj@x.com' => nil,               # no name display
+    'james@x.com' => 'James',
+    'clint@x.com' => 'Clint',
+  }
+  msg.from = {
+    'theboss@x.com' => 'Boss Man'
+  }
+
+  msg.to_s  # ready to be sent via SMTP
+
+
+=== Plain text multipart/mixed message with a file attachment
+
+The multipart/mixed content type can be used to aggregate multiple unrelated
+entities.
+
+  text = DiscreteMediaFactory.create('/tmp/data.txt')
+  image = DiscreteMediaFactory.create('/tmp/ruby.png')
+
+  mixed_msg = MultipartMedia::Mixed.new
+  mixed_msg.attach_entity(image)
+  mixed_msg.add_entity(text)
+  mixed_msg.to_s
+
+
+=== Plain text and HTML multipart/alternative MIME message
+
+The multipart/alternative content type allows for multiple alternatively
+formatted versions of the same content. Clients are then responsible for
+choosing the most suitable version for display.
+
+  text_msg = TextMedia.new(<<-text_data, 'text/plain')
+    *Headline*
+    Ruby is cool!
+  text_data
+
+  html_msg = TextMedia.new(<<-html_data, 'text/html')
+    <html>
+    <body>
+      <h1>Headline</h1>
+      <p>Ruby is cool!</p>
+    </body>
+    </html>
+  html_data
+
+  msg = MultipartMedia::Alternative.new
+  msg.add_entity(html_msg)  # most complex representation must be added first
+  msg.add_entity(text_msg)
+  msg.to_s
+
+
+=== HTML multipart/related MIME email with embedded image
+
+Sometimes it is desirable to send a document that is made up of many separate
+parts. For example, an HTML page with embedded images. The multipart/related
+content type aggregates all the parts and creates the means for the root entity
+to reference the other entities.
+
+  image = DiscreteMediaFactory.create('/tmp/ruby.png')
+  image.content_transfer_encoding = 'binary'
+
+  html_msg = TextMedia.new(<<-html_data, 'text/html; charset=iso-8859-1')
+    <html>
+    <body>
+      <h1>Ruby Image</h1>
+      <p>Check out this cool pic.</p>
+      <img alt="cool ruby" src="cid:#{image.content_id}"/>
+      <p>Wasn't it cool?</p>
+    </body>
+    </html>
+  html_data
+  html_msg.content_transfer_encoding = '7bit'
+
+  related_msg = MultipartMedia::Related.new
+  related_msg.inline_entity(image)
+  related_msg.add_entity(html_msg)
+
+  email_msg = Message.new(related_msg)
+  email_msg.to = {'joe@domain.com' => 'Joe Schmo'}
+  email_msg.from = {'john@domain.com' => 'John Doe'}
+  email_msg.subject = 'Ruby is cool'
+  email_msg.to_s
+
+
+=== HTML form with file upload using multipart/form-data encoding
+
+This example builds a representation of an HTML form that can be POSTed to an
+HTTP server. It contains a single text input and a file input.
+
+  name_field = TextMedia.new('Joe Blow')
+
+  portrait_filename = '/tmp/joe_portrait.jpg'
+  portrait_field = open(portrait_filename) do |f|
+    ImageMedia.new(f.read, 'image/jpeg')                                # explicit content type
+  end
+  portrait_field.content_transfer_encoding = 'binary'
+  
+  form_data = MultipartMedia::FormData.new
+  form_data.add_entity(name_field, 'name')
+  form_data.add_entity(portrait_field, 'portrait', portrait_filename)   # explicity filename
+  form_data.to_s
+
+
+=== HTML form with file upload using multipart/form-data encoding (DiscreteMediaFactory)
+
+The outcome of this example is identical to the previous example. The only
+semantic difference is that the MIME::DiscreteMediaFactory class is used to
+automatically instantiate the MIME::MediaType object.
+
+  name_field = TextMedia.new('Joe Blow')
+
+  portrait_field = DiscreteMediaFactory.create('/tmp/joe_portrait.jpg') # no explicit content type
+  portrait_field.content_transfer_encoding = 'binary'
+  
+  form_data = MultipartMedia::FormData.new
+  form_data.add_entity(name_field, 'name')
+  form_data.add_entity(portrait_field, 'portrait')                      # no explicit filename
+  form_data.to_s
+
+
+== More Examples
+
+For many more examples, check the test class MIMETest.
+
+
+== Contact
+
+Please email inquiries to pachl at ecentryx dot com.
+
+[Home Page] http://mime.rubyforge.org/
+[RubyForge] http://rubyforge.org/projects/mime/
+
+== License
+
+The entire MIME library is free to use under the terms of the Ruby license.

data/Rakefile

@@ -0,0 +1,34 @@
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'rake/gempackagetask'
+
+gem_spec = Gem::Specification.new do |s|
+  s.name = 'mime'
+  s.version = '0.1'
+  s.summary = 'Multipurpose Internet Mail Extensions (MIME) Library'
+  s.test_files = FileList['test/*.rb']
+  s.files = FileList['README', 'Rakefile', 'lib/**/*.rb', 'test/**/*']
+  s.author = 'Clint Pachl'
+  s.email = 'pachl@ecentryx.com'
+  s.homepage = 'mime.rubyforge.org'
+  s.rubyforge_project = 'mime'
+  s.has_rdoc = true
+end
+
+
+Rake::GemPackageTask.new(gem_spec) do |pkg|
+  pkg.need_tar_gz = true
+end
+
+Rake::RDocTask.new do |rd|
+    rd.rdoc_files.include('README', 'lib/')
+    rd.rdoc_dir = 'doc'
+    rd.main = 'README'
+    rd.options << '--all' << '--inline-source'
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/*_test.rb'
+  t.warning = true
+end

data/lib/mime.rb

@@ -0,0 +1,32 @@
+#
+# = Construct Multipurpose Internet Mail Extensions (MIME) messages.
+#
+# ---
+#
+# RFCs referenced during the implementation of this library:
+#
+# * RFC-2822 Internet Message Format (obsoletes 822)
+# * RFC-2045 MIME Part 1: Format of Internet Message Bodies
+# * RFC-2046 MIME Part 2: Media Types
+# * RFC-2047 MIME Part 3: Message Header Extensions for Non-ASCII Text
+# * RFC-2048 MIME Part 4: Registration Procedures
+# * RFC-2049 MIME Part 5: Conformance Criteria and Examples
+#
+# ---
+#
+# See SOAP::MIMEMessage for other implementation ideas.
+#
+module MIME
+
+  VERSION = '0.1'
+
+end
+
+require 'mime/content_types'
+require 'mime/error'
+require 'mime/header_container'
+require 'mime/media_type'
+require 'mime/discrete_media_type'
+require 'mime/composite_media_type'
+require 'mime/message'
+require 'mime/discrete_media_factory'

data/lib/mime/composite_media_type.rb

@@ -0,0 +1,169 @@
+module MIME
+
+  #
+  # Composite entities are handled using MIME mechanisms. A MIME processor must
+  # handle the body directly. A CompositeMediaType object is composed of one or
+  # more CompositeMediaType and/or DiscreteMediaType objects.
+  #
+  # This class is abstract.
+  #
+  class CompositeMediaType < MediaType
+
+    def initialize content_type
+      AbstractClassError.no_instantiation(self, CompositeMediaType)
+
+      super(nil, content_type)
+      @entities = Array.new
+    end
+
+    #
+    # Add a MediaType object to the message.
+    #
+    def add_entity entity
+      raise Error.new('can only add MediaType objects')  unless entity.is_a? MediaType
+      @entities.unshift(entity)
+    end
+
+    #
+    # Attach a MediaType object to the message.
+    #
+    def attach_entity entity, params = {}
+      entity.set_content_disposition('attachment', params)
+      add_entity(entity)
+    end
+
+    #
+    # Inline a MediaType object in the message.
+    #
+    def inline_entity entity, params = {}
+      entity.set_content_disposition('inline', params)
+      add_entity(entity)
+    end
+
+  end
+
+  #
+  # MessageMedia 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 MessageMedia < CompositeMediaType
+  end
+
+  #
+  # The abstract base class for all multipart message subtypes. The entities of
+  # a multipart message are delimited by a unique boundary.
+  #
+  class MultipartMedia < CompositeMediaType
+
+    def initialize content_type
+      AbstractClassError.no_instantiation(self, MultipartMedia)
+      super
+    end
+
+    #
+    # The boundary used to separate the message entities.
+    #
+    def boundary
+      @boundary ||= "Boundary_#{unique_id}"
+    end
+
+    #
+    # Return the multipart representation of the body.
+    #
+    def body
+      all_entities = @entities.join("\r\n--#{boundary}\r\n")
+      "--#{boundary}\r\n#{all_entities}\r\n--#{boundary}--\r\n"
+    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 MultipartMedia::Alternative < MultipartMedia
+
+    #
+    # Returns a MultipartMedia::Alternative object with a content type of
+    # multipart/alternative.
+    #
+    def initialize
+      super("multipart/alternative; boundary=#{boundary}")
+    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 MultipartMedia::FormData < MultipartMedia
+
+    #
+    # Returns a MultipartMedia::FormData object with a content type of
+    # multipart/form-data.
+    #
+    def initialize
+      super("multipart/form-data; boundary=#{boundary}")
+    end
+
+    #
+    # Add the MediaType 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 entity, name, filename = nil
+      entity.set_content_disposition('form-data', 'name' => name, 'filename' => filename)
+      super(entity)
+    end
+
+  end
+
+  #
+  # The Mixed subtype aggregates contextually independent entities.
+  #
+  class MultipartMedia::Mixed < MultipartMedia
+
+    #
+    # Returns a MultipartMedia::Mixed object with a content type of
+    # multipart/mixed.
+    #
+    def initialize
+      super("multipart/mixed; boundary=#{boundary}")
+    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 MultipartMedia::Related < MultipartMedia
+
+    #
+    # Returns a MultipartMedia::Related object with a content type of
+    # multipart/related.
+    #
+    def initialize
+      super("multipart/related; boundary=#{boundary}")
+    end
+
+  end
+
+end