Text.ParserCombinators.Parsec.Rfc2822NS

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 not particularly well tested.

Addendum for Nonstandard Version: This module deviates from the RFC currently in * Allowing for non-standard line endings.

These allowances are subject to change, and should not be used when parsing incoming messages, only for parsing messages that have been stored on disk. The goal of these nonstandard Parsers is to provide a higher probability of parsing Common_ Headers (rather than only those explicitly defined in the RFC) as well as allowing for potential oddities / changes that may occur during storage of an email message. These parsers have be rebranded so as not to conflict with the standard parsers available from the excellent hsemail package, upon which this package depends. For patches to this package only (namely 'hsemail-ns', patches should be sent to [e-mail], for patches to the Proper parsers, you can send them to the original maintainer.

Useful parser combinators

maybeOption :: GenParser tok st a -> GenParser tok st (Maybe a)

Return Nothing if the given parser doesn't match. This combinator is included in the latest parsec distribution as optionMaybe, but ghc-6.6.1 apparently doesn't have it.

unfold :: CharParser a b -> CharParser a b

unfold = between (optional cfws) (optional cfws)

header :: String -> CharParser a b -> CharParser a b

Construct a parser for a message header line from the header's name and a parser for the body.

obsHeader :: String -> CharParser a b -> CharParser a b

Like header, but allows the obsolete white-space rules.

Primitive Tokens (section 3.2.1)

noWsCtl :: CharParser a Char

Match any US-ASCII non-whitespace control character.

text :: CharParser a Char

Match any US-ASCII character except for r, n.

specials :: CharParser a Char

Match any of the RFC's "special" characters: ()<>[]:;@,.\".

Quoted characters (section 3.2.2)

quotedPair :: CharParser a String

Match a "quoted pair". All characters matched by text may be quoted. Note that the parsers returns both characters, the backslash and the actual content.

Folding white space and comments (section 3.2.3)

fws :: CharParser a String

Match "folding whitespace". That is any combination of wsp and crlf followed by wsp.

ctext :: CharParser a Char

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.

comment :: CharParser a String

Match a "comments". That is any combination of ctext, 'quotedPair 's, and fws between brackets. Comments may nest.

cfws :: CharParser a String

Match any combination of fws and comments.

Atom (section 3.2.4)

atext :: CharParser a Char

Match any US-ASCII character except for control characters, specials, or space. atom and dotAtom are made up of this.

atom :: CharParser a String

Match one or more atext characters and skip any preceeding or trailing cfws.

dotAtom :: CharParser a String

Match dotAtomText and skip any preceeding or trailing cfws.

dotAtomText :: CharParser a String

Match two or more atexts interspersed by dots.

Quoted strings (section 3.2.5)

qtext :: CharParser a Char

Match any non-whitespace, non-control US-ASCII character except for "\" and """.

qcontent :: CharParser a String

Match either qtext or 'quotedPair '.

quotedString :: CharParser a String

Match any number of qcontent between double quotes. Any cfws preceeding or following the "atom" is skipped automatically.

Miscellaneous tokens (section 3.2.6)

word :: CharParser a String

Match either atom or quotedString.

phrase :: CharParser a [String]

Match either one or more words or an obsPhrase.

utext :: CharParser a Char

Match any non-whitespace, non-control US-ASCII character except for "\" and """.

unstructured :: CharParser a String

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.

Date and Time Specification (section 3.3)

dateTime :: CharParser a CalendarTime

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 dateTime 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.)

dayOfWeek :: CharParser a Day

This parser will match a dayName, optionally wrapped in folding whitespace, or an obsDayOfWeek and return it's Day value.

dayName :: CharParser a Day

This parser will the abbreviated weekday names ("Mon", "Tue", ...) and return the appropriate Day value.

date :: CharParser a (Int, Month, Int)

This parser will match a date of the form "dd:mm:yyyy" and return a tripple of the form (Int,Month,Int) - corresponding to (year,month,day).

year :: CharParser a Int

This parser will match a four digit number and return it's integer value. No range checking is performed.

month :: CharParser a Month

This parser will match a monthName, optionally wrapped in folding whitespace, or an obsMonth and return it's Month value.

monthName :: CharParser a Month

This parser will the abbreviated month names ("Jan", "Feb", ...) and return the appropriate Month value.

day :: CharParser a Int

Match either an obsDay, or a one or two digit number and return it.

time :: CharParser a (TimeDiff, Int)

This parser will match a timeOfDay specification followed by a zone. It returns the tuple (TimeDiff,Int) corresponding to the return values of either parser.

timeOfDay :: CharParser a TimeDiff

This parser will match a time-of-day specification of "hh:mm" or "hh:mm:ss" and return the corrsponding time as a TimeDiff.

hour :: CharParser a Int

This parser will match a two-digit number and return it's integer value. No range checking is performed.

minute :: CharParser a Int

This parser will match a two-digit number and return it's integer value. No range checking is performed.

second :: CharParser a Int

This parser will match a two-digit number and return it's integer value. No range checking takes place.

zone :: CharParser a Int

This parser will match a timezone specification of the form "+hhmm" or "-hhmm" and return the zone's offset to UTC in seconds as an integer. obsZone is matched as well.

Address Specification (section 3.4)

data NameAddr

A NameAddr is composed of an optional realname a mandatory e-mail address.

Constructors

NameAddr

Fields

nameAddrName :: Maybe String

nameAddrAddr :: String

Instances

Eq NameAddr

Show NameAddr

address :: CharParser a [NameAddr]

Parse a single mailbox or an address group and return the address(es).

mailbox :: CharParser a NameAddr

Parse a nameAddr or an addrSpec and return the address.

nameAddr :: CharParser a NameAddr

Parse an angleAddr, optionally prefaced with a displayName, and return the address.

angleAddr :: CharParser a String

Parse an angle_addr or an obsAngleAddr and return the address.

group :: CharParser a [NameAddr]

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

    parse group "" "my group: [e-mail], [e-mail];"

This input comes out as:

    Right ["[e-mail]","[e-mail]"]

displayName :: CharParser a String

Parse and return a phrase.

mailboxList :: CharParser a [NameAddr]

Parse a list of mailbox addresses, every two addresses being separated by a comma, and return the list of found address(es).

addressList :: CharParser a [NameAddr]

Parse a list of address addresses, every two addresses being separated by a comma, and return the list of found address(es).

Addr-spec specification (section 3.4.1)

addrSpec :: CharParser a String

Parse an "address specification". That is a localPart, followed by an "@" character, followed by a domain. Return the complete address as String, ignoring any whitespace or any comments.

localPart :: CharParser a String

Parse and return a "local part" of an addrSpec. That is either a dotAtom or a quotedString.

domain :: CharParser a String

Parse and return a "domain part" of an addrSpec. That is either a dotAtom or a domainLiteral.

domainLiteral :: CharParser a String

Parse a "domain literal". That is a "[" character, followed by any amount of dcontent, followed by a terminating "]" character. The complete string is returned verbatim.

dcontent :: CharParser a String

Parse and return any characters that are legal in a domainLiteral. That is dtext or a 'quotedPair '.

dtext :: CharParser a Char

Parse and return any ASCII characters except "[", "]", and "\".

Overall message syntax (section 3.5)

data Message

This data type repesents a parsed Internet Message as defined in this RFC. It consists of an arbitrary number of header lines, represented in the Field data type, and a message body, which may be empty.

Constructors

Message [Field] String

Instances

Show Message

message :: CharParser a Message

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.

body :: CharParser a String

This parser will return a message body as specified by this RFC; that is basically any number of text characters, which may be divided into separate lines by crlf.

Field definitions (section 3.6)

data Field

This data type represents any of the header fields defined in this RFC. Each of the various instances contains with the return value of the corresponding parser.

Constructors

OptionalField String String

From [NameAddr]

Sender NameAddr

ReturnPath String

ReplyTo [NameAddr]

To [NameAddr]

Cc [NameAddr]

Bcc [NameAddr]

MessageID String

InReplyTo [String]

References [String]

Subject String

Comments String

Keywords [[String]]

Date CalendarTime

ResentDate CalendarTime

ResentFrom [NameAddr]

ResentSender NameAddr

ResentTo [NameAddr]

ResentCc [NameAddr]

ResentBcc [NameAddr]

ResentMessageID String

ResentReplyTo [NameAddr]

Received ([(String, String)], CalendarTime)

ObsReceived [(String, String)]

Instances

Show Field

fields :: CharParser a [Field]

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 optionalField. 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.

The origination date field (section 3.6.1)

origDate :: CharParser a CalendarTime

Parse a "Date:" header line and return the date it contains a CalendarTime.

Originator fields (section 3.6.2)

from :: CharParser a [NameAddr]

Parse a "From:" header line and return the mailboxList address(es) contained in it.

sender :: CharParser a NameAddr

Parse a "Sender:" header line and return the mailbox address contained in it.

replyTo :: CharParser a [NameAddr]

Parse a "Reply-To:" header line and return the addressList address(es) contained in it.

Destination address fields (section 3.6.3)

to :: CharParser a [NameAddr]

Parse a "To:" header line and return the addressList address(es) contained in it.

cc :: CharParser a [NameAddr]

Parse a "Cc:" header line and return the addressList address(es) contained in it.

bcc :: CharParser a [NameAddr]

Parse a "Bcc:" header line and return the addressList address(es) contained in it.

Identification fields (section 3.6.4)

messageId :: CharParser a String

Parse a "Message-Id:" header line and return the msgId contained in it.

inReplyTo :: CharParser a [String]

Parse a "In-Reply-To:" header line and return the list of msgIds contained in it.

references :: CharParser a [String]

Parse a "References:" header line and return the list of msgIds contained in it.

msgId :: CharParser a String

Parse a "message ID:" and return it. A message ID is almost identical to an angleAddr, but with stricter rules about folding and whitespace.

idLeft :: CharParser a String

Parse a "left ID" part of a msgId. This is almost identical to the localPart of an e-mail address, but with stricter rules about folding and whitespace.

idRight :: CharParser a String

Parse a "right ID" part of a msgId. This is almost identical to the domain of an e-mail address, but with stricter rules about folding and whitespace.

noFoldQuote :: CharParser a String

Parse one or more occurences of qtext or 'quotedPair ' and return the concatenated string. This makes up the idLeft of a msgId.

noFoldLiteral :: CharParser a String

Parse one or more occurences of dtext or 'quotedPair ' and return the concatenated string. This makes up the idRight of a msgId.

Informational fields (section 3.6.5)

subject :: CharParser a String

Parse a "Subject:" header line and return it's contents verbatim.

comments :: CharParser a String

Parse a "Comments:" header line and return it's contents verbatim.

keywords :: CharParser a [[String]]

Parse a "Keywords:" header line and return the list of phrases found. Please not that each phrase is again a list of atoms, as returned by the phrase parser.

Resent fields (section 3.6.6)

resentDate :: CharParser a CalendarTime

Parse a "Resent-Date:" header line and return the date it contains as CalendarTime.

resentFrom :: CharParser a [NameAddr]

Parse a "Resent-From:" header line and return the mailboxList address(es) contained in it.

resentSender :: CharParser a NameAddr

Parse a "Resent-Sender:" header line and return the mailboxList address(es) contained in it.

resentTo :: CharParser a [NameAddr]

Parse a "Resent-To:" header line and return the mailbox address contained in it.

resentCc :: CharParser a [NameAddr]

Parse a "Resent-Cc:" header line and return the addressList address(es) contained in it.

resentBcc :: CharParser a [NameAddr]

Parse a "Resent-Bcc:" header line and return the addressList address(es) contained in it. (This list may be empty.)

resentMsgId :: CharParser a String

Parse a "Resent-Message-ID:" header line and return the msgId contained in it.

Trace fields (section 3.6.7)

returnPath :: CharParser a String

path :: CharParser a String

received :: CharParser a ([(String, String)], CalendarTime)

nameValList :: CharParser a [(String, String)]

nameValPair :: CharParser a (String, String)

itemName :: CharParser a String

itemValue :: CharParser a String

Optional fields (section 3.6.8)

optionalField :: CharParser a (String, String)

Parse an arbitrary header field and return a tuple containing the fieldName and unstructured text of the header. The name will not contain the terminating colon.

fieldName :: CharParser a String

Parse and return an arbitrary header field name. That is one or more ftext characters.

ftext :: CharParser a Char

Match and return any ASCII character except for control characters, whitespace, and ":".

Miscellaneous obsolete tokens (section 4.1)

obsQp :: CharParser a String

Match the obsolete "quoted pair" syntax, which - unlike 'quotedPair ' - allowed any ASCII character to be specified when quoted. The parser will return both, the backslash and the actual character.

obsText :: CharParser a String

Match the obsolete "text" syntax, which - unlike text - allowed "carriage returns" and "linefeeds". This is really weird; you better consult the RFC for details. The parser will return the complete string, including those special characters.

obsChar :: CharParser a Char

Match and return the obsolete "char" syntax, which - unlike character - did not allow "carriage return" and "linefeed".

obsUtext :: CharParser a String

Match and return the obsolete "utext" syntax, which is identical to obsText.

obsPhrase :: CharParser a [String]

Match the obsolete "phrase" syntax, which - unlike phrase - allows dots between tokens.

obsPhraseList :: CharParser a [String]

Match a "phrase list" syntax and return the list of Strings that make up the phrase. In contrast to a phrase, the obsPhraseList separates the individual words by commas. This syntax is - as you will have guessed - obsolete.

Obsolete folding white space (section 4.2)

obsFws :: CharParser a String

Parse and return an "obsolete fws" token. That is at least one wsp character, followed by an arbitrary number (including zero) of crlf followed by at least one more wsp character.

Obsolete Date and Time (section 4.3)

obsDayOfWeek :: CharParser a Day

Parse a dayName but allow for the obsolete folding syntax.

obsYear :: CharParser a Int

Parse a year but allow for a two-digit number (obsolete) and the obsolete folding syntax.

obsMonth :: CharParser a Month

Parse a monthName but allow for the obsolete folding syntax.

obsDay :: CharParser a Int

Parse a day but allow for the obsolete folding syntax.

obsHour :: CharParser a Int

Parse a hour but allow for the obsolete folding syntax.

obsMinute :: CharParser a Int

Parse a minute but allow for the obsolete folding syntax.

obsSecond :: CharParser a Int

Parse a second but allow for the obsolete folding syntax.

obsZone :: CharParser a Int

Match the obsolete zone names and return the appropriate offset.

Obsolete Addressing (section 4.4)

obsAngleAddr :: CharParser a String

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 angleAddr: 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:[e-mail]>

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

    (["example1.org","example2.org"],"[e-mail]")

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 addrSpec address.

obsRoute :: CharParser a [String]

This parser parses the "route" part of obsAngleAddr and returns the list of Strings that make up this route. Relies on obsDomainList for the actual parsing.

obsDomainList :: CharParser a [String]

This parser parses a list of domain names, each of them prefaced with an "at". Multiple names are separated by a comma. The list of domains is returned - and may be empty.

obsLocalPart :: CharParser a String

Parse the obsolete syntax of a localPart, which allowed for more liberal insertion of folding whitespace and comments. The actual string is returned.

obsDomain :: CharParser a String

Parse the obsolete syntax of a domain, which allowed for more liberal insertion of folding whitespace and comments. The actual string is returned.

obsMboxList :: CharParser a [NameAddr]

This parser will match the obsolete syntax for a mailboxList. This one is quite weird: An obsMboxList 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 obsMboxList 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:

    "[e-mail]"

Strange, isn't it?

obsAddrList :: CharParser a [NameAddr]

This parser is identical to obsMboxList but parses a list of addresses rather than mailboxes. The main difference is that an address may contain groups. Please note that as of now, the parser will return a simple list of addresses; the grouping information is lost.

Obsolete header fields (section 4.5)

obsFields :: GenParser Char a [Field]

Obsolete origination date field (section 4.5.1)

obsOrigDate :: CharParser a CalendarTime

Parse a date header line but allow for the obsolete folding syntax.

Obsolete originator fields (section 4.5.2)

obsFrom :: CharParser a [NameAddr]

Parse a from header line but allow for the obsolete folding syntax.

obsSender :: CharParser a NameAddr

Parse a sender header line but allow for the obsolete folding syntax.

obsReplyTo :: CharParser a [NameAddr]

Parse a replyTo header line but allow for the obsolete folding syntax.

Obsolete destination address fields (section 4.5.3)

obsTo :: CharParser a [NameAddr]

Parse a to header line but allow for the obsolete folding syntax.

obsCc :: CharParser a [NameAddr]

Parse a cc header line but allow for the obsolete folding syntax.

obsBcc :: CharParser a [NameAddr]

Parse a bcc header line but allow for the obsolete folding syntax.

Obsolete identification fields (section 4.5.4)

obsMessageId :: CharParser a String

Parse a messageId header line but allow for the obsolete folding syntax.

obsInReplyTo :: CharParser a [String]

Parse an inReplyTo header line but allow for the obsolete folding and the obsolete phrase syntax.

obsReferences :: CharParser a [String]

Parse a references header line but allow for the obsolete folding and the obsolete phrase syntax.

obsIdLeft :: CharParser a String

Parses the "left part" of a message ID, but allows the obsolete syntax, which is identical to a localPart.

obsIdRight :: CharParser a String

Parses the "right part" of a message ID, but allows the obsolete syntax, which is identical to a domain.

Obsolete informational fields (section 4.5.5)

obsSubject :: CharParser a String

Parse a subject header line but allow for the obsolete folding syntax.

obsComments :: CharParser a String

Parse a comments header line but allow for the obsolete folding syntax.

obsKeywords :: CharParser a [String]

Parse a keywords header line but allow for the obsolete folding syntax. Also, this parser accepts obsPhraseList.

Obsolete resent fields (section 4.5.6)

obsResentFrom :: CharParser a [NameAddr]

Parse a resentFrom header line but allow for the obsolete folding syntax.

obsResentSend :: CharParser a NameAddr

Parse a resentSender header line but allow for the obsolete folding syntax.

obsResentDate :: CharParser a CalendarTime

Parse a resentDate header line but allow for the obsolete folding syntax.

obsResentTo :: CharParser a [NameAddr]

Parse a resentTo header line but allow for the obsolete folding syntax.

obsResentCc :: CharParser a [NameAddr]

Parse a resentCc header line but allow for the obsolete folding syntax.

obsResentBcc :: CharParser a [NameAddr]

Parse a resentBcc header line but allow for the obsolete folding syntax.

obsResentMid :: CharParser a String

Parse a resentMsgId header line but allow for the obsolete folding syntax.

obsResentReply :: CharParser a [NameAddr]

Parse a Resent-Reply-To header line but allow for the obsolete folding syntax.

Obsolete trace fields (section 4.5.7)

obsReturn :: CharParser a String

obsReceived :: CharParser a [(String, String)]

obsPath :: CharParser a String

Match obsAngleAddr.

obsOptional :: CharParser a (String, String)

This parser is identical to optionalField but allows the more liberal line-folding syntax between the "fieldName" and the "field text".