hsemail-1.7.7: Internet Message Parsers

Portabilityportable
Stabilityprovisional
Maintainersimons@cryp.to
Safe HaskellSafe-Inferred

Text.ParserCombinators.Parsec.Rfc2822

Contents

Description

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

Synopsis

Useful parser combinators

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

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 bSource

unfold = between (optional cfws) (optional cfws)

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

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

obs_header :: String -> CharParser a b -> CharParser a bSource

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

Primitive Tokens (section 3.2.1)

no_ws_ctl :: CharParser a CharSource

Match any US-ASCII non-whitespace control character.

text :: CharParser a CharSource

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

specials :: CharParser a CharSource

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

Quoted characters (section 3.2.2)

quoted_pair :: CharParser a StringSource

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 StringSource

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

ctext :: CharParser a CharSource

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 StringSource

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

cfws :: CharParser a StringSource

Match any combination of fws and comments.

Atom (section 3.2.4)

atext :: CharParser a CharSource

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

atom :: CharParser a StringSource

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

dot_atom :: CharParser a StringSource

Match dot_atom_text and skip any preceeding or trailing cfws.

dot_atom_text :: CharParser a StringSource

Match two or more atexts interspersed by dots.

Quoted strings (section 3.2.5)

qtext :: CharParser a CharSource

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

quoted_string :: CharParser a StringSource

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

Miscellaneous tokens (section 3.2.6)

phrase :: CharParser a [String]Source

Match either one or more words or an obs_phrase.

utext :: CharParser a CharSource

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

unstructured :: CharParser a StringSource

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)

date_time :: CharParser a CalendarTimeSource

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

day_of_week :: CharParser a DaySource

This parser matches a day_name or an obs_day_of_week (optionally wrapped in folding whitespace) and return its Day value.

day_name :: CharParser a DaySource

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

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

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 IntSource

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

month :: CharParser a MonthSource

This parser will match a month_name, optionally wrapped in folding whitespace, or an obs_month and return its Month value.

month_name :: CharParser a MonthSource

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

day :: CharParser a IntSource

Match a 1 or 2-digit number (day of month), recognizing both standard and obsolete folding syntax.

time :: CharParser a (TimeDiff, Int)Source

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

time_of_day :: CharParser a TimeDiffSource

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 IntSource

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

minute :: CharParser a IntSource

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

second :: CharParser a IntSource

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

zone :: CharParser a IntSource

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. obs_zone is matched as well.

Address Specification (section 3.4)

data NameAddr Source

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

Instances

address :: CharParser a [NameAddr]Source

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

mailbox :: CharParser a NameAddrSource

Parse a name_addr or an addr_spec and return the address.

name_addr :: CharParser a NameAddrSource

Parse an angle_addr, optionally prefaced with a display_name, and return the address.

angle_addr :: CharParser a StringSource

Parse an angle_addr or an obs_angle_addr and return the address.

group :: CharParser a [NameAddr]Source

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;"
Right [NameAddr {nameAddr_name = Nothing, nameAddr_addr = "user1@example.org"},NameAddr {nameAddr_name = Nothing, nameAddr_addr = "user2@example.org"}]

display_name :: CharParser a StringSource

Parse and return a phrase.

mailbox_list :: CharParser a [NameAddr]Source

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

address_list :: CharParser a [NameAddr]Source

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)

addr_spec :: CharParser a StringSource

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

local_part :: CharParser a StringSource

Parse and return a "local part" of an addr_spec. That is either a dot_atom or a quoted_string.

domain :: CharParser a StringSource

Parse and return a "domain part" of an addr_spec. That is either a dot_atom or a domain_literal.

domain_literal :: CharParser a StringSource

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 StringSource

Parse and return any characters that are legal in a domain_literal. That is dtext or a quoted_pair.

dtext :: CharParser a CharSource

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

Overall message syntax (section 3.5)

data GenericMessage a Source

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] a 

Instances

message :: CharParser a MessageSource

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 StringSource

A message body is just an unstructured sequence of characters.

Field definitions (section 3.6)

data Field Source

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.

Instances

fields :: CharParser a [Field]Source

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.

The origination date field (section 3.6.1)

orig_date :: CharParser a CalendarTimeSource

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

Originator fields (section 3.6.2)

from :: CharParser a [NameAddr]Source

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

sender :: CharParser a NameAddrSource

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

reply_to :: CharParser a [NameAddr]Source

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

Destination address fields (section 3.6.3)

to :: CharParser a [NameAddr]Source

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

cc :: CharParser a [NameAddr]Source

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

bcc :: CharParser a [NameAddr]Source

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

Identification fields (section 3.6.4)

message_id :: CharParser a StringSource

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

in_reply_to :: CharParser a [String]Source

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

references :: CharParser a [String]Source

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

msg_id :: CharParser a StringSource

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

id_left :: CharParser a StringSource

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

id_right :: CharParser a StringSource

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

no_fold_quote :: CharParser a StringSource

Parse one or more occurences of qtext or quoted_pair and return the concatenated string. This makes up the id_left of a msg_id.

no_fold_literal :: CharParser a StringSource

Parse one or more occurences of dtext or quoted_pair and return the concatenated string. This makes up the id_right of a msg_id.

Informational fields (section 3.6.5)

subject :: CharParser a StringSource

Parse a "Subject:" header line and return its contents verbatim. Please note that all whitespace and/or comments are preserved, i.e. the result of parsing "Subject: foo" is " foo", not "foo".

comments :: CharParser a StringSource

Parse a "Comments:" header line and return its contents verbatim. Please note that all whitespace and/or comments are preserved, i.e. the result of parsing "Comments: foo" is " foo", not "foo".

keywords :: CharParser a [[String]]Source

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)

resent_date :: CharParser a CalendarTimeSource

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

resent_from :: CharParser a [NameAddr]Source

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

resent_sender :: CharParser a NameAddrSource

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

resent_to :: CharParser a [NameAddr]Source

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

resent_cc :: CharParser a [NameAddr]Source

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

resent_bcc :: CharParser a [NameAddr]Source

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

resent_msg_id :: CharParser a StringSource

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

Trace fields (section 3.6.7)

Optional fields (section 3.6.8)

optional_field :: CharParser a (String, String)Source

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

field_name :: CharParser a StringSource

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

ftext :: CharParser a CharSource

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

Miscellaneous obsolete tokens (section 4.1)

obs_qp :: CharParser a StringSource

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

obs_text :: CharParser a StringSource

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.

obs_char :: CharParser a CharSource

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

obs_utext :: CharParser a StringSource

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

obs_phrase :: CharParser a [String]Source

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

obs_phrase_list :: CharParser a [String]Source

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

Obsolete folding white space (section 4.2)

obs_fws :: CharParser a StringSource

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)

obs_day_of_week :: CharParser a DaySource

Parse a day_name but allow for the obsolete folding syntax.

obs_year :: CharParser a IntSource

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

obs_month :: CharParser a MonthSource

Parse a month_name but allow for the obsolete folding syntax.

obs_day :: CharParser a IntSource

Parse a day but allow for the obsolete folding syntax.

obs_hour :: CharParser a IntSource

Parse a hour but allow for the obsolete folding syntax.

obs_minute :: CharParser a IntSource

Parse a minute but allow for the obsolete folding syntax.

obs_second :: CharParser a IntSource

Parse a second but allow for the obsolete folding syntax.

obs_zone :: CharParser a IntSource

Match the obsolete zone names and return the appropriate offset.

Obsolete Addressing (section 4.4)

obs_angle_addr :: CharParser a StringSource

This parser matches the "obsolete angle address" syntax, a construct that used to be called "route address" in earlier RFCs. It differs from a standard angle_addr in two ways: (1) it allows far more liberal insertion of folding whitespace and comments and (2) the address may contain a "route" (which this parser ignores):

>>> parse obs_angle_addr "" "<@example1.org,@example2.org:joe@example.org>"
Right "<joe@example.org>"

obs_route :: CharParser a [String]Source

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

obs_domain_list :: CharParser a [String]Source

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.

obs_local_part :: CharParser a StringSource

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

obs_domain :: CharParser a StringSource

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

obs_mbox_list :: CharParser a [NameAddr]Source

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. The following example is valid:

>>> parse obs_mbox_list "" ","
Right []

But this one is not:

>>> parse obs_mbox_list "" "joe@example.org"
Left (line 1, column 16):
unexpected end of input
expecting obsolete syntax for a list of mailboxes

obs_addr_list :: CharParser a [NameAddr]Source

This parser is identical to obs_mbox_list 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)

Obsolete origination date field (section 4.5.1)

obs_orig_date :: CharParser a CalendarTimeSource

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

Obsolete originator fields (section 4.5.2)

obs_from :: CharParser a [NameAddr]Source

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

obs_sender :: CharParser a NameAddrSource

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

obs_reply_to :: CharParser a [NameAddr]Source

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

Obsolete destination address fields (section 4.5.3)

obs_to :: CharParser a [NameAddr]Source

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

obs_cc :: CharParser a [NameAddr]Source

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

obs_bcc :: CharParser a [NameAddr]Source

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

Obsolete identification fields (section 4.5.4)

obs_message_id :: CharParser a StringSource

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

obs_in_reply_to :: CharParser a [String]Source

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

obs_references :: CharParser a [String]Source

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

obs_id_left :: CharParser a StringSource

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

obs_id_right :: CharParser a StringSource

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)

obs_subject :: CharParser a StringSource

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

obs_comments :: CharParser a StringSource

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

obs_keywords :: CharParser a [String]Source

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

Obsolete resent fields (section 4.5.6)

obs_resent_from :: CharParser a [NameAddr]Source

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

obs_resent_send :: CharParser a NameAddrSource

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

obs_resent_date :: CharParser a CalendarTimeSource

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

obs_resent_to :: CharParser a [NameAddr]Source

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

obs_resent_cc :: CharParser a [NameAddr]Source

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

obs_resent_bcc :: CharParser a [NameAddr]Source

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

obs_resent_mid :: CharParser a StringSource

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

obs_resent_reply :: CharParser a [NameAddr]Source

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

Obsolete trace fields (section 4.5.7)

obs_optional :: CharParser a (String, String)Source

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