mime 0.1 → 0.2.0

data/README.rdoc

@@ -0,0 +1,303 @@
+== 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   |
+    |      Body      |        (N)         |
+    |   (optional)   |                    |--- RFC822 Message
+    |________________|                    |
+     ________________                     |
+    |                |                    |
+    |  MIME Headers  |                    |
+    |~~~~~~~~~~~~~~~~|  <-- MIME Entity   |
+    |      Body      |        (N+1)       |
+    |   (optional)   |                    |
+    |________________|                    |
+                       -------------------+
+
+
+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 entities and so
+on. However, discrete entities are non-recursive and contain only non-MIME
+bodies.
+
+ 
+== Examples
+
+<em>First things first!</em>
+
+  require 'mime'
+
+
+=== Instantiate a DiscreteMediaType object
+
+Discrete media objects, such as text or video, can be created directly using a
+specific discrete media *class* or indirectly via the *factory*. If the media is
+file backed, like the example below, the factory will open and read the data
+file and determine the MIME type for you.
+
+  file = '/tmp/data.xml'
+
+  text_media = TextMedia.new(File.read(file), 'text/xml')}  # media class
+  text_media = DiscreteMediaFactory.create(file)            # media factory
+
+Discrete media objects can then be embedded in MIME messages as we will see in
+the next example.
+
+
+=== Simple text/plain RFC822 email message
+
+Create a well-formed email message with multiple recipients. The string
+representation of the message (i.e. to_s) can then be sent directly via an
+SMTP client.
+
+  msg = Message.new # blank message with current date and message ID headers
+  msg.date = (Time.now - 3600).rfc2822    # change date
+  msg.subject = 'This is important'       # add subject
+  msg.headers.add('Priority', 'urgent')   # add custom header
+
+  msg.body = TextMedia.new('hello, world!')
+  #
+  # The following two snippets are equivalent to the previous line.
+  #
+  #   msg.body = "\r\nhello, world!"
+  #   msg.header.add('Content-Type', 'text/plain; charset=us-ascii')
+  #
+  #   --OR-- (notice the header must come first, followed by CRLFx2)
+  #
+  #   msg.body = "Content-Type: text/plain; charset=us-ascii\r\n\r\nhello, world!"
+
+  msg.to = {
+    'robot@example.com' => nil,           # no name display
+    'james@example.com' => 'James Smith',
+    'clint@example.com' => 'Clint Pachl',
+  }
+  msg.from = {
+    'boss@example.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, such as text and an image.
+
+  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, such as plain text and HTML. Clients are
+then responsible for choosing the most suitable version for display.
+
+  text_msg = TextMedia.new(<<TEXT_DATA, 'text/plain')
+  **Hello, world!**
+
+  Ruby is cool!
+  TEXT_DATA
+
+  html_msg = TextMedia.new(<<HTML_DATA, 'text/html')
+  <html>
+  <body>
+    <h1>Hello, world!</h1>
+    <p>Ruby is cool!</p>
+  </body>
+  </html>
+  HTML_DATA
+
+  msg = MultipartMedia::Alternative.new
+  msg.add_entity(html_msg)  # most complex representations 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.
+
+Notice the _img_ tag _src_.
+
+  image = DiscreteMediaFactory.create('/tmp/ruby.png')
+  image.content_transfer_encoding = 'binary'
+
+  html_msg = TextMedia.new(<<EOF, 'text/html; charset=iso-8859-1')
+  <html>
+  <body>
+    <h1>Ruby Image</h1>
+    <p>
+      Check out this cool pic.
+      <img alt="ruby is cool" src="cid:#{image.content_id}">
+    </p>
+    <p>Wasn't it cool?</p>
+  </body>
+  </html>
+  EOF
+
+  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@example.com' => 'Joe Schmo'}
+  email_msg.from = {'john@example.com' => 'John Doe'}
+  email_msg.subject = 'Ruby is cool, checkout the picture'
+  email_msg.to_s  # ready to send HTML email with image
+
+
+=== 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,        # TextMedia object
+                       'name')            # field name, i.e. HTML input type=text
+  form_data.add_entity(portrait_field,    # ImageMedia object
+                       'portrait',        # field name, i.e. HTML input type=file
+                       portrait_filename) # suggest filename to server
+  form_data.to_s  # ready to POST via HTTP
+
+
+=== HTML form with file upload via DiscreteMediaFactory
+
+The outcome of this example is identical to the previous one. The only semantic
+difference is that the DiscreteMediaFactory class is used to instantiate the
+image object.
+
+  name_field = TextMedia.new('Joe Blow')
+
+  img = '/tmp/joe_portrait.jpg'
+  portrait_field = DiscreteMediaFactory.create(img)   # automatic 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')    # automatic file name
+  form_data.to_s
+
+
+== More Examples
+
+For many more examples, check the test class MIMETest.
+
+== Links
+
+Ruby Gem      :: https://rubygems.org/gems/mime
+Source Code   :: https://bitbucket.org/pachl/mime/src
+Documentation :: http://ecentryx.com/gems/mime
+
+== History
+
+1. 2008-11-05, v0.1:   First public release
+2. 2013-11-17, v0.2.0: Update for Ruby 1.9.3
+   * Update Rakefile test, package, and rdoc tasks.
+   * Change test suite from Test::Unit to Minitest.
+   * Cleanup existing and add new tests cases.
+   * Clarify code comments and README examples.
+   * Fix content type detection.
+
+== License
+
+({ISC License}[http://opensource.org/licenses/ISC])
+
+Copyright (c) 2014, Clint Pachl <pachl@ecentryx.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

data/Rakefile

@@ -1,34 +1,18 @@
-require 'rake/rdoctask'
+require 'rdoc/task'
+require 'rubygems/package_task'
 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|
+Gem::PackageTask.new(eval File.read('mime.gemspec')) 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'
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.rdoc'
+  rdoc.rdoc_dir = 'doc'
+  rdoc.rdoc_files.include('README.rdoc', 'lib/')
+  rdoc.options << "--all"
 end
 
 Rake::TestTask.new do |t|
-  t.libs << 'lib'
-  t.pattern = 'test/*_test.rb'
   t.warning = true
 end

data/lib/mime.rb

@@ -18,7 +18,7 @@
 #
 module MIME
 
-  VERSION = '0.1'
+  VERSION = '0.2.0'
 
 end
 

data/lib/mime/discrete_media_factory.rb

@@ -42,15 +42,14 @@ module MIME
           fname = file
         end
 
-        raise UnknownContentError  unless ctype
-
         media_obj = 
-          case ctype.match(/^(\w+)\//)[1]
+          case ctype.to_s[/^(\w+)\//, 1]
           when 'application'; ApplicationMedia.new(cntnt, ctype)
           when 'audio'      ; AudioMedia.new(cntnt, ctype)
           when 'image'      ; ImageMedia.new(cntnt, ctype)
           when 'text'       ; TextMedia.new(cntnt, ctype)
           when 'video'      ; VideoMedia.new(cntnt, ctype)
+          else raise UnknownContentError, "invalid content type: #{ctype}"
           end
 
         class << media_obj;  attr_accessor :path  end

data/lib/mime/headers/internet.rb

@@ -6,14 +6,21 @@ module MIME
     #
     module Internet
 
-      attr_reader :date, :from, :to
-      attr_reader :cc, :bcc, :reply_to, :message_id
-      attr_reader :comments, :keywords, :subject
-
-
-      #
-      # Required Headers
-      #
+      attr_reader(
+        # Required Headers
+        :to,
+        :from,
+        :date, 
+
+        # Optional Headers
+        :cc,
+        :bcc,
+        :reply_to,
+        :message_id,
+        :comments,
+        :keywords,
+        :subject
+      )
 
       def date= date
         @date = date
@@ -30,11 +37,6 @@ module MIME
         headers.add('To', @to)
       end
 
-
-      #
-      # Optional Headers
-      #
-
       def cc= list
         @cc = stringify_email_list(list)
         headers.add('Cc', @cc)

data/lib/mime/headers/mime.rb

@@ -6,13 +6,14 @@ module MIME
     #
     module MIME
 
-      attr_reader :mime_version,
+      attr_reader(
+        :mime_version,
         :content_description,
         :content_disposition,
         :content_id,
         :content_transfer_encoding,
         :content_type
-
+      )
 
       #
       # Describes the content, which can be useful for non-MIME clients.
@@ -47,11 +48,11 @@ module MIME
       # The mechanism used for encoding the top-level message content.
       #
       # Common Encoding Mechanisms
-      # 1. 7bit
-      # 2. 8bit
-      # 3. binary
-      # 4. quoted-printable
-      # 5. base64
+      # * 7bit
+      # * 8bit
+      # * binary
+      # * quoted-printable
+      # * base64
       #
       def content_transfer_encoding= encoding
         @content_transfer_encoding = encoding
@@ -63,11 +64,11 @@ module MIME
       # the form <em>media-type/subtype</em>.
       #
       # Common Content Types
-      # 1. application/octet-stream
-      # 2. audio/mpeg
-      # 3. image/jpeg
-      # 4. text/plain
-      # 5. video/mpeg
+      # * application/octet-stream
+      # * audio/mpeg
+      # * image/jpeg
+      # * text/plain
+      # * video/mpeg
       #
       def content_type= type
         @content_type = type
@@ -88,11 +89,11 @@ module MIME
       # +type+ is the disposition type of either "inline" or "attachment".
       # +params+ is a Hash with zero or more of the following keys:
       #
-      #   * filename          => name of file
-      #   * creation-date     => RFC2822 data-time
-      #   * modification-date => RFC2822 data-time 
-      #   * read-date         => RFC2822 data-time
-      #   * size              => file size in octets
+      # +filename+          :: name of file
+      # +creation-date+     :: RFC2822 data-time
+      # +modification-date+ :: RFC2822 data-time 
+      # +read-date+         :: RFC2822 data-time
+      # +size+              :: file size in octets
       #
       # The values for the *-date keys may use Time::rfc2822.
       #
@@ -113,6 +114,5 @@ module MIME
       end
 
     end
-
   end
 end