mime 0.3.0 → 0.4.0

data/README.rdoc

@@ -9,80 +9,80 @@ 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::CompositeMedia for a description of composite media types
+* MIME::DiscreteMedia for a description of discrete media types
 * MIME::DiscreteMediaFactory for easy programming of discrete media types
 * MIME::ContentFormats for ways to encode/decode 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,
+== Media Inheritance Heirarchy
+
+   Media*
+     ^
+     |
+     |--DiscreteMedia*
+     |    ^
+     |    |
+     |    |--Application
+     |    |--Audio
+     |    |--Image
+     |    |--Text
+     |    +--Video
+     |
+     +--CompositeMedia*
+          ^
+          |
+          |--Message**
+          |    ^
+          |    |
+          |    |--ExternalBody**
+          |    |--Partial**
+          |    +--RFC822**
+          |
+          +--Multipart*
+               ^
+               |
+               |--Alternative
+               |--Digest**
+               |--Encrypted**
+               |--FormData
+               |--Mixed
+               |--Parallel**
+               |--Related
+               |--Report**
+               +--Signed**
+
+    * Abstract Class
+   ** Not implemented
+
+
+== MIME Message Format
+
+
+    ________________  -------------------+
+   |                |                    |
+   | RFC822 & MIME  |                    |
+   |    Headers     |                    |
+   |________________|                    |
+    ________________                     |
+   |                |                    |
+   |  MIME Headers  |                    |
+   |~~~~~~~~~~~~~~~~|  <-- MIME Entity*  |--- RFC822/MIME
+   |     Body*      |        (N)         |      Message
+   |________________|                    |
+    ________________                     |
+   |                |                    |
+   |  MIME Headers  |                    |
+   |~~~~~~~~~~~~~~~~|  <-- MIME Entity*  |
+   |     Body*      |        (N+1)       |
+   |________________|                    |
+                      -------------------+
+
+    * Optional
+
+
+Each <em>MIME Entity</em> must be a discrete (MIME::DiscreteMedia) or
+composite (MIME::CompositeMedia) 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.
@@ -96,7 +96,7 @@ bodies.
   include MIME   # allow ommision of "MIME::" namespace in examples below
 
 
-=== Instantiate a DiscreteMediaType object
+=== Instantiate a DiscreteMedia 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
@@ -105,8 +105,8 @@ file and determine the MIME type for you.
 
   file = '/tmp/data.xml'
 
-  text_media = TextMedia.new(File.read(file), 'xml')}       # media class
-  text_media = DiscreteMediaFactory.create(file)            # media factory
+  text_media = Text.new(File.read(file), '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.
@@ -118,34 +118,52 @@ 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 = Mail.new    # blank message with current date and message ID headers
+  msg.date -= 3600                        # change date to 1 hour ago
   msg.subject = 'This is important'       # add subject
-  msg.headers.add('Priority', 'urgent')   # add custom header
+  msg.headers.set('Priority', 'urgent')   # add custom header
 
-  msg.body = TextMedia.new('hello, world!', 'plain', 'charset' => 'us-ascii')
+  msg.body = Text.new('hello, world!', 'plain', 'charset' => 'us-ascii')
   #
-  # The following two snippets are equivalent to the previous line.
+  # The previous line is equivalent to the following snippet:
   #
-  #   msg.body = "\r\nhello, world!"
-  #   msg.header.add('Content-Type', 'text/plain; charset=us-ascii')
-  #
-  #   --OR-- (notice the header must come first, followed by two CRLFs)
-  #
-  #   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.body = 'hello, world!'
+  #   msg.headers.set('Content-Type', 'text/plain; charset=us-ascii')
+
+  msg.from = {'boss@example.com' => 'Boss Man'}            # mailbox hash
+  msg.bcc  = 'boss+home@example.com'                       # mailbox string
+  msg.cc   = %w(secretary@example.com manager@example.com) # mailbox array
+  msg.to   = {
+    'list@example.com' => nil,                             # no name display
+    'john@example.com' => 'John Doe',
+    'jane@example.com' => 'Jane Doe',
   }
 
   msg.to_s  # ready to be sent via SMTP
 
 
+=== RFC822 email message with image body
+
+Embedding a single image within an email message requires a single discrete 
+media image. However, embedding multiple images requires a multipart/mixed 
+composite media type to encapsulate all of the discrete media images.
+
+==== Email body with single image
+
+  img = Image.new(File.read('screenshot.png'), 'png')
+  img.disposition = 'inline'
+  img.description = 'My screenshot'
+  email = Mail.new(img)
+
+==== Email body with multiple images
+
+  msg = Multipart::Mixed.new
+  msg.inline Image.new(File.read('screenshot1.png'), 'png')
+  msg.inline Image.new(File.read('screenshot2.png'), 'png')
+  msg.description = 'My screenshots'
+  email = Mail.new(msg)
+
+
 === Plain text multipart/mixed message with a file attachment
 
 The multipart/mixed content type can be used to aggregate multiple unrelated
@@ -154,9 +172,9 @@ 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 = Multipart::Mixed.new
+  mixed_msg.add(text)
+  mixed_msg.attach(image)
   mixed_msg.to_s
 
 
@@ -166,13 +184,13 @@ 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, 'plain')
+  text_msg = Text.new(<<TEXT_DATA, 'plain')
   **Hello, world!**
 
   Ruby is cool!
   TEXT_DATA
 
-  html_msg = TextMedia.new(<<HTML_DATA, 'html')
+  html_msg = Text.new(<<HTML_DATA, 'html')
   <html>
   <body>
     <h1>Hello, world!</h1>
@@ -181,10 +199,10 @@ then responsible for choosing the most suitable version for display.
   </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
+  msg = Multipart::Alternative.new
+  msg.add(text_msg)  # add the simplest representations first
+  msg.add(html_msg)
+  msg.to_s           # or send in an email: Mail.new(msg)
 
 
 === HTML multipart/related MIME email with embedded image
@@ -194,35 +212,33 @@ 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_.
+Notice the _src_ of the _img_ tag.
 
   image = DiscreteMediaFactory.create('/tmp/ruby.png')
-  image.content_transfer_encoding = 'binary'
+  image.transfer_encoding = 'binary' # could base64 encode the image instead
 
-  html_msg = TextMedia.new(<<EOF, 'html', 'charset' => 'iso-8859-1')
+  html_msg = Text.new(<<EOF, '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}">
+      <img alt="ruby is cool" src="cid:#{image.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)
+  related_msg = Multipart::Related.new
+  related_msg.add(html_msg)
+  related_msg.inline(image)
 
-  email_msg = Message.new(related_msg)
-  email_msg.to = {'joe@example.com' => 'Joe Schmo'}
-  email_msg.from = {'john@example.com' => 'John Doe'}
+  email_msg         = Mail.new(related_msg)
+  email_msg.to      = 'jane@example.com'
+  email_msg.from    = 'john@example.com'
   email_msg.subject = 'Ruby is cool, checkout the picture'
-  email_msg.to_s  # ready to send HTML email with image
+  email_msg.to_s    # ready to send HTML email with image
 
 
 === HTML form with file upload using multipart/form-data encoding
@@ -230,39 +246,34 @@ Notice the _img_ tag _src_.
 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, 'jpeg')        # explicit content type
-  end
-  portrait_field.content_transfer_encoding = 'binary'
+  name_field     = Text.new('Joe Blow')
+  portrait_path  = '/tmp/joe_portrait.jpg'
+  portrait_field = Image.new(File.read(portrait_path), 'jpeg')
+  portrait_field.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
+  form_data = Multipart::FormData.new
+  form_data.add(name_field,      # field value
+                'name')          # field name, i.e. HTML input type=text
+  form_data.add(portrait_field,  # field value
+                'portrait',      # field name, i.e. HTML input type=file
+                portrait_path)   # suggest image 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 module is used to instantiate the
-image object.
+image object and automatically set the content type and FormData filename.
 
-  name_field = TextMedia.new('Joe Blow')
+  name_field     = Text.new('Joe Blow')
+  portrait_path  = '/tmp/joe_portrait.jpg'
+  portrait_field = DiscreteMediaFactory.create(portrait_path)
+  portrait_field.transfer_encoding = 'binary'
 
-  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 = Multipart::FormData.new
+  form_data.add(name_field, 'name')
+  form_data.add(portrait_field, 'portrait')
   form_data.to_s
 
 
@@ -284,19 +295,27 @@ appropriate.
     "80 characters and will be soft line wrapped after the word '80'.\n\n"
 
   flowed_txt = ContentFormats::TextFlowed.encode(long_paragraph * 2)
-  flowed_msg = TextMedia.new(flowed_txt, 'plain', 'format' => 'flowed')
-  flowed_msg.to_s # neatly formatted text compatible with large to small screens
+  flowed_msg = Text.new(flowed_txt, 'plain', 'format' => 'flowed')
+  flowed_msg.to_s # neatly formatted text compatible with small to large screens
 
 
 == 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
+Validators    :: Please check *all* of your messages using the following lint 
+                 tools and report errors to pachl@ecentryx.com with "Ruby MIME" 
+                 in the subject.
+
+                 - http://www.apps.ietf.org/content/message-lint
+                 - http://tools.ietf.org/tools/msglint
+
 
 == History
 
@@ -313,6 +332,39 @@ Documentation :: http://ecentryx.com/gems/mime
    * Simplify API of DiscreteMediaType subclasses.
    * Disallow Content-Type changes after instantiating DiscreteMediaType.
    * Add flowed format support for text/plain (RFC 2646). 
+4. 2014-04-18, v0.4.0
+   * <b>Major API disruption!</b>
+     * Rename classes:
+       - HeaderContainter => Header
+       - remove "Media" suffix from the 5 DiscreteMedia and 2 CompositeMedia 
+         subclasses. See revision 4876b1390624 for details.
+       - MIME::Message => MIME::Mail
+     * Rename methods:
+       - remove "_entity" suffix from add, inline, and attach in CompositeMedia.
+       - remove "content_" prefix from id, disposition, description, and 
+         transfer_encoding in Headers::MIME.
+     * Remove methods:
+       - Header#add
+     * Add methods:
+       - Header#set (replace Header#add)
+       - Header#get
+       - Header#delete
+     * Reverse order of entities in CompositeMedia::Body, which most likely
+       reverses all CompositeMedia #add, #inline, and #attach method calls.
+       See revision a51745f346b5 for details.
+   * Other changes
+     * Use From header field domain in the Message-ID header.
+     * Add more randomness when generating header IDs.
+     * Header field names are now case-insensitive to comply with RFCs.
+     * Accept String, Array, and Hash for originator and destination mailboxes.
+     * Add CompositeMedia::Body class for nesting MIME entities.
+     * Improve docs and examples for Content-Disposition (inline/attachment).
+     * FIX: remove trailing CRLF in Mail#to_s and update tests.
+     * Add README links to message lint tools on IETF.org.
+     * Add Send, In-Reply-To, and References RFC 5322 header fields.
+     * Comply with RFC regarding parameter quoting in header field bodies.
+       I.e., do not quote atom/dot-atom parameter values.
+     * Many fixes and improvements in code, tests, documentation, and examples.
 
 
 == License