This module provides parsers for the grammar defined in RFC2822, "Internet Message Format", http://www.faqs.org/rfcs/rfc2822.html.

Please note: The module is a mess. I keep it around as a reminder that it needs to be rewritten, mostly. Nevertheless, some parsers -- like date_time, for example -- are genuinely useful.

Match any non-whitespace, non-control character except for "(", ")", and "\". This is used to describe the legal content of comments.

Note: This parser accepts 8-bit characters, even though this is not legal according to the RFC. Unfortunately, 8-bit content in comments has become fairly common in the real world, so we'll just accept the fact.

Match any number of utext tokens.

"Unstructured text" is used in free text fields such as subject. Please note that any comments or whitespace that prefaces or follows the actual utext is included in the returned string.

Parse a date and time specification of the form

   Thu, 19 Dec 2002 20:35:46 +0200

where the weekday specification "Thu," is optional. The parser returns a CalendarTime, which is set to the appropriate values. Note, though, that not all fields of CalendarTime will necessarily be set correctly! Obviously, when no weekday has been provided, the parser will set this field to Monday - regardless of whether the day actually is a monday or not. Similarly, the day of the year will always be returned as 0. The timezone name will always be empty: "".

Nor will the date_time parser perform any consistency checking. It will accept

    40 Apr 2002 13:12 +0100

as a perfectly valid date.

In order to get all fields set to meaningful values, and in order to verify the date's consistency, you will have to feed it into any of the conversion routines provided in System.Time, such as toClockTime. (When doing this, keep in mind that most functions return local time. This will not necessarily be the time you're expecting.)

Parse a "group" of addresses. That is a display_name, followed by a colon, optionally followed by a mailbox_list, followed by a semicolon. The found address(es) are returned - what may be none. Here is an example:

    parse group "" "my group: user1@example.org, user2@example.org;"

This input comes out as:

    Right ["user1@example.org","user2@example.org"]

Parse a complete message as defined by this RFC and it broken down into the separate header fields and the message body. Header lines, which contain syntax errors, will not cause the parser to abort. Rather, these headers will appear as OptionalFields (which are unparsed) in the resulting Message. A message must be really, really badly broken for this parser to fail.

This behaviour was chosen because it is impossible to predict what the user of this module considers to be a fatal error; traditionally, parsers are very forgiving when it comes to Internet messages.

If you want to implement a really strict parser, you'll have to put the appropriate parser together yourself. You'll find that this is rather easy to do. Refer to the fields parser for further details.

This parser will parse an arbitrary number of header fields as defined in this RFC. For each field, an appropriate Field value is created, all of them making up the Field list that this parser returns.

If you look at the implementation of this parser, you will find that it uses Parsec's try modifier around all of the fields. The idea behind this is that fields, which contain syntax errors, fall back to the catch-all optional_field. Thus, this parser will hardly ever return a syntax error -- what conforms with the idea that any message that can possibly be accepted should be.

This parser will match the "obsolete angle address" syntax. This construct used to be known as a "route address" in earlier RFCs. There are two differences between this construct and the angle_addr: For one - as usual -, the obsolete form allows for more liberal insertion of folding whitespace and comments.

Secondly, and more importantly, angle addresses used to allow the (optional) specification of a "route". The newer version does not. Such a routing address looks like this:

    <@example1.org,@example2.org:simons@example.org>

The parser will return a tuple that - in case of the above address - looks like this:

    (["example1.org","example2.org"],"simons@example.org")

The first part contains a list of hosts that constitute the route part. This list may be empty! The second part of the tuple is the actual addr_spec address.

This parser will match the obsolete syntax for a mailbox_list. This one is quite weird: An obs_mbox_list contains an arbitrary number of mailboxes - including none -, which are separated by commas. But you may have multiple consecutive commas without giving a mailbox. You may also have a valid obs_mbox_list that contains no mailbox at all. On the other hand, you must have at least one comma.

So, this input is perfectly valid:

    ","

But this one is - contrary to all intuition - not:

    "simons@example.org"

Strange, isn't it?