rmail 0.17

data/NEWS

@@ -0,0 +1,309 @@
+= Changes in RubyMail 0.17 (released 2004-04-27)
+
+- Handle parsing addresses with non-ASCII display names.  We don't do
+  anything intelligent with the non-ASCII data, but it is passed
+  through in its original (invalid) non-encoded form.
+
+- Look for From_ lines only on the first line when parsing a message.
+
+- RMail::Header#subject= now sets the header field name to "Subject"
+  instead of "subject" since some mail reading software is case
+  sensitive and can't understand "subject: foo".
+
+- The RMail parser now requires only whitespace after MIME multipart
+  boundary lines.  This violates RFC2046's "NOTE TO IMPLEMENTORS"
+  documented in testparsermultipart.rb's test_multipart_data_12, but
+  it allows real-world messages created by Eudora to be parsed.
+
+= Changes in RubyMail 0.16 (released 2003-12-26)
+
+- Ruby 1.8.1 compatibility fixes only.
+
+= Changes in RubyMail 0.15 (released 2003-09-17)
+
+- Ruby 1.8.0 compatibility fixes only.
+
+= Changes in RubyMail 0.14 (released 2003-02-08)
+
+- Improve RDoc documentation of the library.
+
+  - Add file level comments.
+  - No longer document RMail::Parser::PushbackReader and
+    RMail::Parser::Multipart, as they are used only internally or by
+    those who really want to dig deep into the library.  I also think
+    they might be changing soon.
+
+- Add ability to
+    require 'rmail'
+  and get all of RubyMail.
+
+- Switch to the BSD license, mainly so the license of RubyMail is not
+  confusing.
+
+= Changes in RubyMail 0.13 (released 2003-02-01)
+
+- Add convenience methods to RMail::Header that allow easy
+  manipulation of the To, Cc, Bcc, Reply-To, Date, Subject and
+  Message-Id fields.  This includes unique Message-Id generation code
+  and robust Date field parsing and formatting.
+
+- Add RMail::Header#set, to delete existing fields of the same name
+  and then add a new one.
+
+- RMail::Address.parse now returns an RMail::Address::List instead of
+  an Array (existing code still works, since RMail::Address::List
+  inherits from Array).
+
+- Add RMail::Address#<=>, RMail::Address#hash and RMail::Address#eql?
+  methods.  This allows arrays of RMail::Address to be sorted as well
+  as allowing RMail::Address to be placed in a hash (which in turn
+  allows Array#uniq to work when holding RMail::Address objects).
+
+- Add an RMail::Mailbox::MBoxReader.each_message method.
+
+- Deleted the rmail/header/field.rb field and incorporated
+  RMail::Header::Field into rmail/header.rb.
+
+- Improve uniqueness of the MIME boundary generation by including
+  Time.now.tv_usec.
+
+- Correct broken docs for RMail::Header#match and RMail::Header#match?
+
+= Changes in RubyMail 0.12 (released 2003-01-13)
+
+- Add an install.rb script.
+
+= Changes in RubyMail 0.11 (released 2003-01-11)
+
+- parse->serialize "transparency" greatly improved.  This means that
+  when you parse a message and then serialize it back out you almost
+  always get the exact same message back.  This is true for all single
+  part messages as well as all validly formatted multipart MIME
+  messages (and even the most common invalidly formatted ones).
+
+  The result is that RMail can now be used safely in mail filters
+  without risking damaging cryptographic signatures in the mails.
+
+- RMail::Header#add now uses to_str instead of to_s to convert
+  arguments to strings.  This makes it behave more like standard
+  Ruby classes.
+
+- RMail::Mailbox::MBoxReader now always makes sure the last piece of
+  data returned for each message is the end of line terminator, even
+  if one isn't present in the input.
+
+- RMail::Parser::PushbackReader#read now takes nil argument to mean
+  "read all available input."  Derived classes should now override
+  the #read_chunk method instead of #read.
+
+= Changes in RubyMail 0.10 (released 2002-12-13)
+
+- Added rmail/mailbox/mboxreader.rb to the distribution.
+
+= Changes in RubyMail 0.9 (released 2002-11-30)
+
+- New RMail::Mailbox.parse_mbox method that can be used to conveniently
+  read raw messages out of a Unix mbox mailbox.
+
+- New RMail::Mailbox::MBoxReader class in
+  rmail/mailbox/mboxreader.rb.  This class can be used to easily read
+  messages out of a file in Unix "mbox" format.
+
+- The RMail::Parser::PushbackReader class
+  has been documented.  It has moved out of rmail/parser/multipart.rb
+  into rmail/parser/pushbackreader.rb
+
+- Various documentation fixes.  E.g. RMail::Parser.parse can take a
+  string as well as an IO object.
+
+- The RMail::Parser::PushbackReader has a setable chunk size.  This
+  is useful mostly for testing.
+
+- Fix an uncaught exception when parsing multipart MIME messages that
+  contain only a preamble and an epilogue but no body parts.
+
+- Fix a bug where RMail::Parser.multipart? would not return true if the
+  multipart message actually didn't have any parts.
+
+= Changes in RubyMail 0.8 (released 2002-03-18)
+
+- The following has been removed from RubyMail and made part of the
+  RubyFilter package:
+
+  - All scripts that were in the RubyMail 0.7 bin directory.
+  - Mail::LDA
+  - Mail::Deliver
+  - Mail::KeyedMailbox
+  - Mail::MTA
+  - Mail::AddressTagger
+
+  This keeps RubyMail a small and simple mail package, and provides
+  RubyFilter as an example of how to use RubyMail to write a mail
+  filter.
+
+- The Mail module has been renamed to RMail.  I think "Mail" should
+  be reserved for things included in the standard distribution of
+  Ruby.
+
+-  RMail::Header#match and match? don't require the name or value
+   arguments to be a case insensitive Regexps.  Also, when the value
+   argument is converted to a string, it is passed through
+   Regexp::escape first.
+
+- RMail::Parser#parse can now parse from a string.
+
+- Mail::Address#comments= can now take a simpple string to set just
+  one comment.
+
+= Changes in RubyMail 0.7 (released 2002-02-26)
+
+- A new chunked input scheme that makes parsing huge messages about 7
+  times faster in ruby 1.7 and 50 times faster in ruby 1.6.
+
+  When parsing a huge message that has a 2 megabyte attachment,
+  RubyMail running under ruby 1.7 is now faster than any email
+  package for ruby, perl or python.
+
+  I wrote a benchmark that reads a 2 megabyte email from a file and
+  writes it out again, doing this 100 times.  The results are:
+
+    ruby 1.7.2 w/rubymail (100 times)
+         5.96s user  7.98s system 13.94s total
+    ruby 1.6.6 w/rubymail (100 times)
+        76.91s user  8.62s system 85.53s total
+    ruby 1.7.2 w/tmail 0.10.1 (100 times)
+         9.85s user 24.21s system 34.06s total
+    ruby 1.6.6 w/tmail 0.10.0 (100 times)
+        201.89s user 15.75s system 217.64s total
+    python 2.2 w/email (100 times)
+        76.73 user 15.16s system 91.89s total
+    perl 5.006001 w/mimetools 5.411  (parsing on disk) (100 times)
+        190.11s user 25.25s system 215.36s total
+    perl 5.006001 w/mimetools 5.411  (parsing in memory) (100 times)
+        962.69s user  6.77s system 969.46s total
+
+  This change also paves the way for streaming large messages
+  to disk when they start to get huge, so RAM isn't needlessly
+  used up.
+
+- Delivery to mbox files improved.
+
+  - won't sleep forever waiting for the mailbox lock (flock)
+  - won't delivery to files that don't look like an mbox
+    (e.g. it is not a file, not in the right format).
+  - delivering to '/dev/null' is now a simple nop.
+
+- Use the new File#fsync method when available in all of the mail
+  delivery functions.
+
+- Add bin/rsendmail.rb as another example of how I'm using RubyMail.
+
+- A new Mail::AddressTagger class, included for fun.  Requires the
+  hmac-sha1 class (available in the ruby-hmac package on RAA).
+
+= Changes in RubyMail 0.6 (released 2002-02-15)
+
+- Multipart MIME support.
+
+  - Mail::Parser now parses arbitrarily nested multipart MIME messages.
+
+  - For the sake of dealing with multipart MIME messages, add the
+    following methods to Mail::Message: preamble, epilogue, multipart?,
+    add_part, decode, part.
+
+- A new Mail::AddressTagger class, for tagging addresses with
+  cryptographically verifiable extensions akin to TMDA.  Requires the
+  hmac-sha1 module from the RAA.  (experimental, I don't currently
+  use this)
+
+- A new Mail::Message#== method.
+
+- A new Mail::Serialize class that can serialize a Mail::Message.
+
+= Changes in RubyMail 0.5 (released 2002-02-02)
+
+- The rdeliver.rb script is now fully documented.
+
+- The rdeliver.rb script now evaluates the .rdeliver file in the
+  context of a Deliver class (as opposed to simply loading it).  The
+  .rdeliver file must now define a Deliver#main method, where the
+  simplest .rdeliver file would be:
+
+    def main
+      lda.save("INBOX")
+    end
+
+- Add a KeyedMailbox class that can be used to implement simple
+  mailing list style confirmations.
+
+- Add a message= method to Mail::DeliveryAgent.  This lets delivery
+  scripts change the message being delivered.
+
+- Re-wrote the RFC2822 address parser.  It is now more strict about
+  what it considers a valid address.
+
+= Changes in RubyMail 0.4 (released 2002-01-17)
+
+- The bin/rdeliver.rb script is now tested.  Got rid of
+  bin/rdeliver-wrap.rb.
+
+- Mail::DeliveryAgent::DeliveryStatus renamed to
+  Mail::DeliveryAgent::DeliveryComplete.
+  Mail::DeliveryAgent::DeliverFailure renamed to
+  Mail::DeliveryAgent::DeliveryPipeFailure.
+
+- Mail::Deliver.deliver_mbox now uses File::SYNC to write the
+  message.
+
+- Mail::Header and Mail::Message no longer understand how to parse
+  messages.  Message parsing has been moved to Mail::Parser.
+  Mail::Parser uses the public API of Mail::Header and Mail::Message
+  to build up the message.
+
+- The Mail::Header API has been greatly changed.  It is now more like
+  Array and Hash.
+
+- Mail::Deliver supports delivery to qmail style Maildir mailboxes.
+  Mail::DeliveryAgent#save will now deliver to a Maildir if the
+  folder's name ends in a slash.  E.g. "/home/user/Maildir/".
+
+- Mail::DeliveryAgent no longer logs an abstract of the message being
+  delivered.  All logging is up to the users of Mail::DeliveryAgent.
+
+= Changes in RubyMail 0.3
+
+- Add Mail::Header.length and Mail::Header.size methods.  Add
+  Mail::Header.match and Mail::Header.match? methods.
+
+- Move deliver.rb to bin/rdeliver-wrap.rb and main.rb to
+  bin/rdeliver.rb.  These are workable local delivery agent scripts
+  (suitable for running from .forward).
+
+- New Mail::MTA module that provides constants for exit codes.
+
+- New features for Mail::DeliveryAgent.  Now Mail::DeliveryAgent never
+  calls exit, instead it throws DeliveryStatus exceptions.  There is
+  also a new Mail::DeliveryAgent.process method that allows you to use
+  Mail::DeliveryAgent in block form.  Mail:DeliveryAgent.exitcode will
+  return the correct exit code for a given DeliveryStatus exception.
+
+= Changes in RubyMail 0.2
+
+- HTML API documentation is now available in the doc subdirectory.
+
+- Mail::DeliveryAgent::strip_tag is now
+  Mail::DeliveryAgent::strip_field_name.
+
+- Mail::Deliver::deliver_pipe implemented.  Mail::DeliveryAgent#pipe
+  implemented.
+
+- Mail::DeliveryAgent#pipe and Mail::DeliveryAgent#save now report
+  success or failure with DeliverySuccess and DeliveryFailure
+  exceptions.  Mail::DeliveryAgent#reject and
+  Mail::DeliveryAgent#defer do not yet use the exceptions (they still
+  call exit).
+
+- Now runs clean under "ruby -w"
+
+- Now works with newer rubyunit versions.
+

data/NOTES

@@ -0,0 +1,14 @@
+-*- outline -*-
+
+* Why RubyMail can't be completely transparent
+
+    RubyMail parses the MIME message into a document structure.  If
+    the MIME message is invalid, RubyMail might discard invalid
+    portions, etc.  Also, if you parse and then serialize a
+    RMail::Message, empty lines may be deleted or inserted around a
+    MIME boundary.
+
+    For these reasons, if you require a message to be output exactly
+    as it is put in, I suggest that you do not filter it *through*
+    RubyMail.  Instead, parse the message and decide what to do with
+    it, and then save the original message.

data/README

@@ -0,0 +1,83 @@
+= RubyMail
+
+This is RubyMail, a lightweight mail library containing various
+utility classes and modules that allow Ruby scripts to parse,
+modify, and generate MIME mail messages.
+
+= Requirements
+
+Ruby 1.6.7 (or newer) or Ruby 1.8.*.  Only tested under Linux, should
+be fine under any Unix.
+
+= Documentation
+
+The documentation is in RDoc format in the doc subdirectory.  Aside
+from the API reference, you will be interested in guide/Intro.txt and
+guide/TableOfContents.txt.
+
+= Install
+
+Type the following while in the package directory:
+
+  ruby install.rb config
+  ruby install.rb setup
+  ruby install.rb install
+
+You may need special permissions to execute the last line.  If you
+want to just install RubyMail to a custom location, just copy the
+rmail subdirectory manually.
+
+= Status
+
+This package works well, but I consider all API subject to change.
+
+I very much appreciate suggestions and comments, but please think
+twice about using this for production use just yet.
+
+= Tests?
+
+This package has a complete unit test suite (requires RubyUnit to
+run).  Currently all of my e-mail is processed by this library.
+
+= Why?
+
+It is fun.
+
+One use for RubyMail is the RubyFilter package, available at:
+
+    http://www.lickey.com/rubyfilter/
+
+= Alternatives
+
+You might check out TMail as well.
+
+= Support
+
+To reach the author of RubyMail, send mail to matt@lickey.com.
+
+= License
+
+ Copyright (C) 2001, 2002, 2003, 2004 Matt Armstrong.  All rights
+ reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+
+ 1. Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+ 3. The name of the author may not be used to endorse or promote products
+    derived from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+ NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/THANKS

@@ -0,0 +1,25 @@
+= Thanks to Python's email module for:
+
+- The idea of separating parsing and serialization from the mail
+  classes themselves.
+- A lot of the MIME multipart API.
+
+= Thanks to Perl's MimeTools for:
+
+- Showing me this can all be done in the scripting language (no C
+  extensions necessary).
+- Accessing MIME parts via a File like API (thereby allowing them to
+  be stored on disk).
+
+= People:
+
+"Yoshinori K. Okuji" <okuji-at-enbug-dot-org>
+
+- Code to parse messages from strings (though since then I did it a
+  much simpler way).
+- Numerous other API suggestions and improvements.
+
+Booker Bense <bbense-at-SLAC-dot-Stanford-dot-EDU>
+
+- For prodding me to implement mbox mailbox parsing (and an initial
+  implementation).  It took me months, but I did it!

data/TODO

@@ -0,0 +1,112 @@
+In rough priority order...but please let me know if something you need
+is missing.
+
+= FIXME
+
+- StreamHandler should get preamble_begin and preamble_end callbacks.
+  Same for epilogue_begin, epilogue_end.
+
+= STOLEN
+
+- Header continuation issue:
+  https://sourceforge.net/tracker/?func=detail&atid=105470&aid=504152&group_id=5470
+- Subject: =?ISO-8859-1?Q?=24=A3_Kills_IRB?=
+
+= Documentation
+
+- Make it clear that all strings the library works with are the ASCII
+  strings that are part of the RFC2822 message -- not strings in any
+  other charset.
+
+- Update Intro.txt, write MIME.txt and other Guides.
+
+= Features
+
+- RFC2231
+  http://mail.python.org/pipermail/email-sig/2003-November/000032.html
+
+- Smart handling of charset issues for text/ types.
+
+  [Goal] allow setting the body part to a given piece of data, and
+         RMail handles setting the appropriate MIME headers.  This
+         requires the data to have a known charset.
+
+  Maybe this plays into the encoding solution below.
+
+- Base64 and quoted-printable encoding
+
+  [Goal] allow setting the body part to a given piece of data, and
+         RMail handles setting the appropriate MIME headers and
+         possibly quoted-printable or base64 transcoding it if
+         appropriate.
+
+  This may be best done by introducing an RMail::TransferEncodedString
+  class that knows whether it is transcoded as binary,
+  quoted-printable, base64, etc.  You would set RMail::Message#body to
+  a TransferEncodedString and RMail::Message would set the appropriate
+  MIME headers.  If at serialization time the message body were set to
+  a plain String, then RMail::Message would transcode it into base64.
+
+- An RMail::Message#attach method that takes care of setting
+  content-disposition, etc.
+
+- Header folding in RMail::Header.
+
+- A small wrapper around Net::SMTP#send_mail that takes care of:
+  - parsing recipients out of the various message headers
+  - deleting the Bcc: header
+  - sending the message
+
+- Provide a way to parse just the message headers, leaving the rest in
+  the input stream (for use by RubyFilter).  This also implies a
+  feature that parses a message body given a RMail::Header object and
+  an input stream.  This should be easy -- read line by line until you
+  get an empty line or EOF, then pass that off to parse_header as a
+  string to be parsed.  Parsing the body can just use a
+  PushbackReader.
+
+- Handle different end of line terminators everywhere (for both
+  parsing and generating).
+
+- Provide some way when parsing a message to start spooling to disk
+  for really large messages.  This would be easy to do depending on
+  how message body transparency is implemented.
+
+- MIME charset support in header fields and message bodies.  This
+  requires m18n support in ruby, so it won't be coming soon.
+
+- Maildir parsing.
+
+- Simplify the Parser such that the class used to hold the parse
+  result can be easily changed and so the memory used can be
+  minimized.
+
+  The idea is to support "bogofilter" style parsing where the data of
+  the parse is immediately processed and thrown away but the structure
+  and content of the parsed message is important.
+
+  This may require extensions to header parsing, where things like the
+  important MIME header fields can be parsed without creating a whole
+  RMail::Header object.
+
+= Minor Features
+
+- Untainting of email addresses.  See Perl's CGI::Untaint::email.
+
+- Parser for Received: headers.  See Perl's Mail::Field::Received.
+
+= Documentation Tasks
+
+- A "howto" like documentation.
+
+  - How to write out a base64 encoded MIME part to a file.
+  - How to parse a unix MBOX file.
+  - MIME operations (see RFC2047)
+    - Character sets in message bodies
+    - Non-textual message bodies
+    - Multi-part message bodies
+    - Textual header information in character sets other than
+      US-ASCII.
+
+- Go through every class and make sure the methods are sorted in a
+  sensible order so the RDoc output is nice.